> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mira-app.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> Common MIRA error messages and how to resolve them.

## 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** |

<Note>
  Edit this page — [Open a pull
  request](https://github.com/satyendra2013/mira-app/edit/main/docs/reference/error-reference.mdx)
</Note>