Troubleshooting and FAQ
Common problems and questions, with their causes and fixes.
Starting the gateway
no config found
Prism looks for the file given with -c, then prism.yaml in the current folder, then ~/.config/prism/prism.yaml. Create one of these, or pass the path with -c. The beginner guide has a working example.
parsing config: ... field ... not found
The file has a key Prism does not know, often a typo or a key at the wrong indentation. Prism refuses unknown keys on purpose. Compare with the reference.
references unknown model
A rule, routing.default or a fallback chain names a model that is not in any provider's models list. The message says which one. Check the spelling against prism models.
server.api_keys is required when listening on non-loopback address
You set listen to an address other computers can reach, such as 0.0.0.0:8130. Prism refuses to do that without client keys. Add server.api_keys with at least one long random value, or go back to 127.0.0.1:8130.
is declared by both
Two models share the same id or alias. Every id and alias must be unique across all providers.
Requests
A request returns 404 with unknown model
The model in the request is not an id or alias Prism knows. The error lists the names that are available. Use one of them, or auto.
A request returns 401
You set server.api_keys, and the tool did not send one of them. Put the key in the tool's API key field.
My tool says it needs a real API key
Type dummy when server.api_keys is empty. Prism keeps the real provider keys; the tool never needs them.
A provider answers with an authentication error
The environment variable named in api_key_env was not set in the terminal that started prism serve. Set it and restart the gateway. A wrong key is a 4xx error, which Prism passes back instead of failing over.
Requests with tools or images fail with 400
Some routes cannot carry them. The anthropic provider type, the /v1/messages endpoint and the subscription types (claude-code, codex-cli) refuse tool definitions; the subscription types also refuse images. Route such requests to an openai-type provider, for example with a vision: true rule.
hybrid pipelines are not implemented yet
Model names starting with pipeline: are reserved for a planned feature. Use a model name or auto.
The first answer from a local model is very slow
Ollama loads a model into memory on first use, which can take a while for large models. Later answers are faster. The desktop companion's Run button loads a model ahead of time.
Routing, failover and budget
auto picked a model I did not expect
Run prism explain "your prompt" and read profile and reason. The task and language come from simple text checks, so a prompt can be classified differently from what you meant. Reorder your rules or add a more specific one.
Failover did not happen
Prism fails over only on connection errors, timeouts, 429 and 5xx errors, and never after a streamed answer has started. Other errors, such as a bad request, go straight back to your tool. Check the chain with prism explain -m <model> "hello".
The budget is spent but cloud models still answer
The budget only works through a budget_exceeded: true rule, and rules only apply when the request asks for auto. A request that names a cloud model goes to it. Make sure the rule is near the top of the list.
The costs look wrong
Prism uses the prices you wrote in cost. Check them against your provider's current price list. Entries for streams without token counts are estimates.
Questions
Does Prism send my prompts anywhere?
Only to the provider that answers each request. Prism stores no prompts in its usage records. Projects in the dashboard save their chats as files on your machine.
Can I run it on a server for my team?
Yes. Set server.listen to a reachable address and server.api_keys to keys for your users. Prism speaks plain HTTP, so put a TLS reverse proxy in front of it on any network you do not fully trust.
Is there a macOS version or a .deb?
No. The gateway is built for Linux and Windows, and the desktop companion for Linux. Linux packages are .rpm and Arch; the single binary works on any distribution, including Debian and Ubuntu.
Is there an Android app?
The source code includes an Android companion, but it is not built or released.
Reporting problems
Open an issue on GitHub. Do not paste API keys or your full prism.yaml if it contains keys.