Error Reference - MIRA

Engine errors

Error	Cause	Fix
`Engine failed to start`	Python subprocess exited on launch	Check that bundled Python is intact; reinstall MIRA if needed
`Engine timeout`	The engine did not respond within the configured timeout	Increase the timeout in engine settings, or reduce context size
`Max iterations reached`	RLM hit `maxIterations` without a solution	Increase `maxIterations` in the active skill or RLM settings
`Context window exceeded`	Input + history exceeds the model’s context limit	Reduce `Max context tokens` in NAE settings, or start a new session
`Engine restarting…`	The Python subprocess crashed and is being restarted	Wait 5–10 seconds; the engine recovers automatically

Provider errors

Error	Cause	Fix
`401 Unauthorized`	API key is invalid or expired	Rotate the key in Settings → Providers
`403 Forbidden`	Your account does not have access to this model	Upgrade your provider plan or request model access
`429 Too Many Requests`	Rate limit hit	Wait and retry; reduce eval concurrency
`503 Service Unavailable`	Provider API is down	Check the provider’s status page and retry
`ECONNREFUSED`	Cannot reach the provider endpoint	Check your internet connection; for Ollama, ensure `ollama serve` is running

Document errors

Error	Cause	Fix
`Unsupported file format`	File extension is not in the supported list	Convert the document to a supported format
`File too large`	Document exceeds the 50 MB limit	Split the document or reduce its size
`Parse failed`	The parser could not extract text	The file may be corrupted or password-protected
`No text extracted`	Parser ran but found no readable text	The file may be a scanned image; convert with OCR first

MCP errors

Error	Cause	Fix
`MCP server failed to start`	The stdio command exited immediately	Run the command in a terminal to see the error
`MCP connection refused`	SSE server is not running on the URL	Verify the server is running and the URL is correct
`Tool call failed`	The MCP tool returned an error	Check the Activity Center for the tool’s error message
`Tool not found`	Engine called a tool that no longer exists	Reconnect or update the MCP server

Eval errors

Error	Cause	Fix
`Embedding model not configured`	Semantic similarity eval requires an embedding model	Set one in Settings → Eval Framework
`Judge model not configured`	LLM judge eval requires a judge model	Set one in Settings → Eval Framework
`Case timed out`	Engine took too long to respond for a case	Increase engine timeout or simplify the case input

Startup errors

Error	Cause	Fix
`Database migration failed`	`mira.db` schema is from an incompatible version	Back up and delete `mira.db`; MIRA creates a fresh one on next launch
`Keychain access denied`	OS denied MIRA’s `safeStorage` encryption access	Reinstall MIRA; on macOS ensure MIRA has Full Disk Access in System Settings → Privacy & Security

Edit this page — Open a pull request