Troubleshooting
Specific symptoms, why they happen, and what to change.
Each page here covers one symptom: what you see, why it happens, and the fix. For the full list of error cases with their meanings, see the errors reference.
Tools
AIError.missingToolResults
A conversation was sent on with tool calls that have no matching results.
AIError.unknownTool
The model called a tool that was not in the tools array.
AIError.invalidToolInput
Tool arguments failed schema validation, so the tool never ran.
AIError.invalidToolApproval
An approval response failed verification.
A tool is offered but never runs
The model calls a tool and the loop stops instead of executing it.
Output
AIError.noObjectGenerated
Structured output did not parse or validate.
AIError.decoding
A response arrived but did not match the expected shape.
Limits and timeouts
Running out of context on a long run
A long agent loop fails or degrades once the history outgrows the window.
AIError.timedOut
A timeout fired. The scope tells you which one and what to change.
Providers and auth
HTTP 401 from a provider
The API key is missing, wrong, or not reaching the provider.
Cannot reach a local model server
Ollama or another local server is not running, or is on a different port.
AIError.authorizationRequired from an MCP server
A hosted MCP server needs an OAuth sign-in that could not be refreshed.
Apple on-device model is unavailable
Foundation Models is not ready on this machine.