> ## Documentation Index > Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Fix common problems with installing and running o4. This page covers the problems people run into most often, with the message you see and how to fix it. If your problem isn't here, check [where o4 keeps its logs](#logs-and-diagnostics), then [report it](/help/feedback). Start by checking which o4 you're running: ```bash theme={null} command -v o4 o4 --version ``` ## Installation and PATH ### `command not found: o4` The install folder isn't on your `PATH`. The install script puts o4 in `~/.local/bin` (or the folder in `O4_INSTALL_DIR`) and prints a note when that folder isn't on your `PATH`. Add it to your shell profile, then open a new terminal: ```bash theme={null} echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc ``` Use `~/.bashrc` instead if your shell is bash. See [Install o4](/installation#add-o4-to-your-path). ### The wrong version runs If you installed o4 more than one way, for example with the script and with Homebrew, the first copy on your `PATH` wins. List every copy: ```bash theme={null} which -a o4 ``` Remove the copies you don't want, or reorder your `PATH`. ### `new o4 installed · restart to update` A running session keeps using the binary it started with, even after you install a new version. While the session waits at the prompt, o4 checks every few seconds whether the file it was started from has been replaced. If it has, o4 shows `new o4 installed · restart to update` on the second row below the prompt until you restart. Quit, then run the `o4 resume ` command from the summary o4 prints when it exits, to continue the same session on the new version. ## Models and API keys ### `Model '' not found` ```text theme={null} Error: Model 'anthropic:claude-nope-9' not found. Use `o4 --list-models` to see available models. ``` The model you passed with `-m` doesn't exist in o4's model list. Check the spelling, and list the available models: ```bash theme={null} o4 --list-models ``` `-m` accepts `provider:model`, `provider/model` or a bare model ID, for example `-m anthropic:claude-sonnet-4-6`. Inside a session, `/model ` reports the same problem as `Model '' not found. Use /model to see available models.` If the model saved in your settings no longer exists, for example after a model was retired, o4 starts on a fallback model and opens the setup wizard so you can pick another. In print mode, it uses the fallback model without telling you, so pass `-m` in scripts. With `--no-onboarding`, it exits with `Configured model '' is not selectable` instead; pass `-m` or run once without `--no-onboarding`. See [The default model](/models/overview#the-default-model) for how o4 picks the fallback. o4 refreshes its model list from the o4 model catalog about once a week. To get newly released models sooner, run `/models-update`, or open `/config model` and choose **Refresh catalog**. See [Choosing a model](/models/overview). ### o4 starts on a different model than you picked `/model`, `Ctrl+M` and `Alt+M` switch only the current session, so the next `o4` starts on your saved `model` setting again. To change the default, pick a model from the **Model** row of `/config model`, run `/onboard`, or set `model` in `~/.o4/settings.json`. In a trusted workspace, a `model` in the project's `.o4/settings.json` overrides it, and `-m` overrides both for one run. See [The default model](/models/overview#the-default-model). ### `No default model configured` ```text theme={null} Error: No default model configured. Run without --no-onboarding to choose one, or pass `-m `. ``` You ran o4 with `--no-onboarding` before choosing a model. Run `o4` once without it to go through the setup wizard, or pass a model with `-m`. ### `No API key found for ` or an authentication error o4 has no key for the provider of the model you picked, or the key is wrong or expired. A wrong key usually shows up as an HTTP 401 error on the first request. Run `/auth status` to see the current provider and whether its key comes from your settings or the environment. Then fix it one of these ways: * Run `/config providers` in o4 and enter the key in the **API key** row. * Set the provider's environment variable, such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, before starting o4. A key stored in `~/.o4/settings.json` wins over the variable, so remove a wrong stored key first. * Run `/onboard` to go through the setup wizard again. Then send your message again. See [Providers and API keys](/models/providers). For Claude and ChatGPT subscriptions, see [Claude and ChatGPT subscriptions](/models/subscriptions). ### Rate limits and temporary provider errors When a provider answers with a temporary error, such as HTTP 429 (rate limited), 408, 409, 500, 502, 503, 504 or 529, o4 retries the turn up to 3 times, waiting 1, 2 and then 4 seconds. It doesn't retry automatically if part of the reply or a tool call had already arrived, so nothing is repeated. The status line shows each attempt: ```text theme={null} Retrying (1/3) in 1s: ... ``` In print mode the same information goes to standard error as `[retry 1/3 in 1s] ...`. If all retries fail, o4 shows `Agent error:` with the provider's message, and you can run `/retry` to send your last message again. If you hit rate limits often, wait for your provider's limit window to reset, switch to another model with `/model`, or set up the [model router](/models/router) with `/router setup` so o4 can fall back to another model after a provider error. For ChatGPT subscriptions, a quota error can say `Codex will not retry quota responses automatically`, but o4 still retries an HTTP 429 three times within seconds, which rarely helps with a plan limit. Wait for the limit window to reset. See [Claude and ChatGPT subscriptions](/models/subscriptions). `/status` shows your account's usage limits for providers that report them. ## Permissions and the sandbox ### A command or tool is blocked Two separate systems can stop the model: * **Permissions** decide whether a tool call runs at all. In print mode, o4 can't show approval prompts. It runs in `auto` unless you pass `--permission-mode`, and with `ask` or `accept-edits`, any call that would ask is refused. Pick a different `--permission-mode`, or add a permission rule. See [Permissions](/safety/permissions#print-mode). * **The sandbox** limits what an approved shell command can write and which hosts it can reach. A write outside the allowed folders fails with a permission error from the operating system, and a request to a host that isn't allowed fails or asks you first. See [Sandbox](/safety/sandbox). To let commands write to another folder, add it to `allowedPaths` in the `[sandbox]` config, or start o4 with `--add-dir` and `--sandbox workspace-write`. To let them reach a host, choose **Always allow this domain** when o4 asks, or add the host to `allowedDomains`. Press `Alt+S` to switch the sandbox tier for the session. See [Sandbox](/safety/sandbox#configure-the-sandbox). ### Linux: `sandbox restrictions require bubblewrap` ```text theme={null} o4 refused to run command: sandbox restrictions require bubblewrap (`bwrap`) on Linux; install it or explicitly use the open tier ``` On Linux, the `guarded` and `airlock` tiers need bubblewrap installed as `/usr/bin/bwrap` or `/bin/bwrap`. Install your distribution's `bubblewrap` package, or switch to the `open` tier for the session with `Alt+S` if you accept running commands unsandboxed. ### A file tool refuses a path o4's file tools only work inside the project and your home directory, and they never touch credential locations such as `~/.ssh`, `~/.aws` or `~/.o4/settings.json`. The error says which rule applied: ```text theme={null} Path '/opt/data/report.csv' is outside the project directory — o4 only reads/writes within the project or home directory Path '/Users/you/.ssh/id_ed25519' is in a protected location (/Users/you/.ssh) — o4 will not access credentials or key material ``` When you pass `-C` or `--add-dir`, they only work inside those directories, and a path elsewhere fails with `is outside the workspace and additional directories`. See [Tools](/reference/tools#files). ### Project hooks, MCP servers or settings are ignored Project configuration only loads in a trusted workspace. Review the repository, then run `o4 trust` in its root. When the project has a `.o4/config.toml`, `.o4/config.local.toml` or `.o4.md` that o4 skipped, `~/.o4/o4.log` has a warning that starts with `Ignored project configuration because this workspace is not trusted.` See [Workspace trust](/safety/workspace-trust). o4 also reads the project's `.o4/` folder only from the directory you start it in, or the one you pass with `-C`, not from parent folders. If you start o4 in a subfolder, start it in the project root instead, or pass `-C`. See [Configuration files](/configuration/overview). A `settings.json` with a single invalid value, such as `"yes"` for a boolean, is ignored completely and without a message, so all your preferences seem to reset at once. See [Configuration reference](/reference/configuration#settings-json). A `.o4/harness.toml` that isn't valid TOML is skipped without a log line too; see [Harness guides and sensors](/extend/harness#check-a-harness-file). ## MCP servers ### `Registry search failed with status 404 Not Found` ```text theme={null} Error: Failed to search MCP registry: Registry search failed with status 404 Not Found Error: MCP server 'github' not found in registry. Run 'o4 mcp search' to find servers. ``` In o4 0.2.74, lookups in the MCP registry fail, because the registry no longer serves the address o4 queries. `o4 mcp search` and the **Registry** tab in `/mcp` show the first error, and `o4 mcp add ` and `/mcp add ` report that the server wasn't found, even for servers that exist. Add the server with **Add server** in `/mcp`, or by editing `.o4/.mcp.json` or `~/.o4/.mcp.json`. See [MCP servers](/extend/mcp). ### An MCP server doesn't start or its tools are missing Open `/mcp` and check the **Errors** tab, which lists servers that failed to start with the error message. A slow server may need more than the default 10 seconds to start; raise `startup_timeout_sec` in its entry. Project servers in `.o4/.mcp.json` only load in a trusted workspace (see [above](#project-hooks-mcp-servers-or-settings-are-ignored)). After you fix the config, run `/mcp restart `. See [MCP servers](/extend/mcp). ## Language servers ### `LSP error -32002` In o4 0.2.74, the `lsp` tool doesn't set up the language server session before it sends a request, so standard servers such as `rust-analyzer` and `clangd` refuse every request with this "not initialized" error. There is no setting that fixes it. For code navigation, use the code index instead. See [Language servers and formatters](/extend/lsp-and-formatters) and [Code intelligence](/guides/code-intelligence). ## The terminal display ### Colors look wrong or washed out o4 detects your terminal's color support from `COLORTERM` and `TERM`. It uses full color when `COLORTERM` is `truecolor` or `24bit`, 256 colors when `TERM` contains `256color`, and 16 colors otherwise. If your terminal supports more than o4 detects, set the variable before starting o4: ```bash theme={null} export COLORTERM=truecolor ``` The default `auto` theme uses your terminal's own colors and picks light or dark colors to match its background. If the result is hard to read, choose another theme with the **Theme** row in `/config appearance`. See [Themes and display](/configuration/appearance#themes). ### Icons show as boxes or question marks o4 uses Nerd Font icons by default. If your terminal font doesn't include them, turn off **Nerd fonts** in `/config appearance`, and o4 shows text such as `[copy]` and `>` in their place. Other symbols, such as `●`, `✦` and box-drawing lines, are standard Unicode and stay. If those also look wrong, your font or terminal is missing Unicode support; [screen reader mode](#using-a-screen-reader) replaces box drawing with plain ASCII. ### Using a screen reader Start o4 with `--accessibility`, or turn on **Screen reader** in `/config appearance`, for output that works better with screen readers. The `O4_ACCESSIBILITY` and `ACCESSIBILITY_ENABLED` environment variables have no effect in o4 0.2.74. If screen reader mode stays on after you stop passing `--accessibility`, you changed a display row while the flag was on, which saved the setting. Turn **Screen reader** off in `/config appearance`. See [Screen reader mode](/configuration/appearance#screen-reader-mode). ### Display or appearance settings don't stick Timestamps, the thinking display, animations and screen reader mode are saved in `~/.o4/display.json`. If you edit that file by hand and leave out `show_timestamps`, `show_thinking` or `animations`, or the file isn't valid JSON, o4 ignores it and uses the defaults for all four. The other appearance settings live in `~/.o4/settings.json`, which o4 ignores completely if any value in it is invalid. Change these settings in `/config` (the **Appearance** and **Reasoning** tabs) rather than by hand, or see [display.json](/reference/configuration#display-json). ### The interface is slow or lags Keystrokes and redraws can lag when the machine is busy, for example during a large build in the same checkout, or when the terminal can't keep up with output. The o4 process is still working. Wait for the build to finish, or run heavy builds in another checkout. o4 logs every frame that takes 500 ms or longer to draw as a `slow render frame` warning in `~/.o4/o4.log`, with timings and counts but no text from your session. Include those lines when you report a slow interface. For per-frame timings, see `O4_TUI_RENDER_TIMING` in [Environment variables](/reference/environment-variables). ## Logs and diagnostics o4 writes diagnostics to `~/.o4/o4.log`. By default it only logs warnings and errors. To log more, set `RUST_LOG` before starting o4: ```bash theme={null} RUST_LOG=debug o4 ``` `RUST_LOG` takes the usual `tracing` filter syntax, so `RUST_LOG=o4_coding_agent=debug,warn` limits the extra detail to o4's own code. Every o4 process, including print mode and subcommands, appends to the same file, and o4 never truncates or rotates it. To start fresh before you reproduce a problem, delete the file; o4 creates it again with permissions that only let your user read it. Other files that help when something goes wrong: | What | Where | | - | - | | Diagnostics log | `~/.o4/o4.log` | | Daemon log | `~/.o4/daemon/daemon.log` | | Session debriefs | `.o4/debriefs/.md` in your project | | Local usage events | `~/.o4/telemetry/events.jsonl` | ### Show your setup with `/doctor` Run `/doctor` in a session to print the details that help most in a bug report: the o4 version, the current model, the working directory, your shell, your terminal (`TERM`) and your home directory. For example: ```text theme={null} o4 0.2.74 diagnostics model: claude-sonnet-4-6 cwd: /Users/you/code/my-project shell: /bin/zsh terminal: xterm-256color home: /Users/you ``` `/env` prints the same details without the terminal and home directory. Neither command checks your setup for problems; they only report it. ### Session debriefs When a session ends, o4 writes a debrief to `.o4/debriefs/.md` in the project. It lists the files that changed, the commands that ran, what was verified and what was assumed, open threads and decisions. o4 keeps the 20 most recent debriefs per project. To see the debrief for the current session, run `/debrief`. The open threads and decisions are summarized by the current model. ### Check the context window and usage `/context` shows how the context window is used, and `/stats` shows session and tool usage. `/stats` reads the local usage events, so it shows nothing new while telemetry is off; see [Telemetry and privacy](/help/telemetry-and-privacy). From a script, `o4 -p "/context --json"` and `o4 -p "/stats --json"` print the same reports as JSON without calling the model. See [Context and cost](/guides/context-and-cost). ### Check the system prompt `o4 --print-system-prompt` prints the full system prompt, with the prompt profile it chose and its size, and exits without calling the model. Use it to check that your project instructions and custom prompt are loaded. See [Project instructions](/configuration/project-instructions). ## Still stuck Report the problem with `/bug` from inside o4, or open an issue on the [o4 issue tracker](https://github.com/Open4rena/o4-releases/issues). `/bug` fills in your o4 version, operating system and model. If you file by hand, include the output of `o4 --version`, or of `/doctor` if you can open a session. Say what you ran and what you expected, and add relevant lines from `~/.o4/o4.log`, with secrets removed. See [Feedback and support](/help/feedback).