Skip to main content

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.

​
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: 
--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. 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: 
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). 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

CodeMeaning
0Success
1Validation 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.
  • File an issue on GitHub with the command you ran, the redacted output, and your mulerouter --version.