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