> ## Documentation Index
> Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to fix them

## Configuration

**`Error: API key not found. Please set MULEROUTER_API_KEY environment variable, or provide it via --api-key argument.`**

Run `mulerouter config` to see what the CLI has resolved. Then either:

* `export MULEROUTER_API_KEY=sk-...` in your shell, or
* add `MULEROUTER_API_KEY=sk-...` to a `.env` file in the working directory, or
* pass `--api-key` on the command line.

**`Error: Invalid site: ...`**

For self-hosted gateways use `--base-url` / `MULEROUTER_BASE_URL` instead.

**The `.env` file isn't taking effect.**

`.env` is loaded once per process, from the **current working directory**,
and it never overrides variables already set in the environment. Check
`printenv | grep MULEROUTER` — if `export` already set it, `.env` is a no-op.

## Endpoint resolution

**`Error: Model endpoint '...' not found.`**

Spelling or version mismatch. Run `mulerouter list` (or `mulerouter list --json | jq '.models[].model_id'`) and copy the identifier exactly.

**`Error: Multiple actions found for '...'. Please specify one of: ...`**

The model has multiple actions (e.g. `generation` and `edit`). Use the full
three-part identifier: `provider/model/action`.

## Parameter validation

**`Error: Invalid value for --duration: 'abc' is not a valid integer.`**

The CLI coerces strings into the parameter's declared type. Pass a numeric
value, or quote the right thing — `--duration 10`, not `--duration "10s"`.

**`Error: Invalid value for --size: '4K'. Valid choices: 1280*720, 960*960, ...`**

The parameter has an `enum`. `mulerouter params <endpoint>` shows the allowed
values.

**`Error: Missing required parameter(s): --prompt.`**

Required parameters must be present. The error message lists every flag that
needs a value.

**`Error: Empty value for required parameter(s): --prompt.`**

You passed `--prompt ""` or similar. Required string parameters must be
non-empty.

**`Error: Parameter '...' must be a valid JSON array.`**

Array parameters take a JSON-encoded string:

```bash theme={null}
--images '["https://example.com/a.png","https://example.com/b.png"]'
```

Mind the outer single quotes so your shell doesn't strip the inner double
quotes.

## Image inputs

**`Warning: File not found for --image: ...`**

The path didn't resolve as a file. The CLI continues, treating the value as a
literal URL string. Usually a typo in the path.

**`Error: File '...' has extension '.foo' which is not an allowed image format.`**

Only image extensions are accepted (`.png`, `.jpg`, ...) — see
[Local image inputs](/docs/cli/workflows/image-inputs).

**`Error: File '...' is 24.0MB, exceeding the 20MB limit`**

Resize, re-encode, or host the file yourself and pass the URL instead.

**`Error: Access denied: '...' is in a sensitive system directory`** /
**`...is in a sensitive home directory`**

System directories (`/etc`, `/proc`, ...) and sensitive home directories
(`~/.ssh`, `~/.aws`, ...) are blocked by design — move the file somewhere else.

## Networking and timeouts

**The task hits the `--max-wait` budget before completing.**

The task is not cancelled — only the CLI poller gave up. Re-attach with
[`mulerouter status`](/docs/cli/commands/status):

```bash theme={null}
mulerouter status <api-path> <task-id> --wait --max-wait 1800
```

For genuinely long jobs, switch to `--no-wait` on submission and resume
polling later (see [Async tasks](/docs/cli/workflows/async-tasks)).

**Transient 5xx or network errors.**

The built-in client retries with exponential backoff (up to 3 attempts by
default). Persistent failures usually indicate either an upstream incident or
a bad `--base-url`.

## Exit codes

| Code | Meaning                                                                          |
| ---- | -------------------------------------------------------------------------------- |
| `0`  | Success                                                                          |
| `1`  | Validation error, configuration error, transport error, or terminal task failure |

When parsing JSON output programmatically, always check `$?` first — a non-zero
exit means the JSON may contain an `error` field rather than results.

## Still stuck?

* Re-run with the explicit URL to rule out site/proxy issues:
  `--base-url https://api.mulerouter.ai`.
* Compare against the underlying HTTP API in the
  [API reference](/docs/api-reference/introduction).
* File an issue on
  [GitHub](https://github.com/openmule/mulerouter-cli/issues) with the
  command you ran, the redacted output, and your `mulerouter --version`.