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:
~/.bashrc instead if your shell is bash. See Install o4.
The wrong version runs
If you installed o4 more than one way, for example with the script and with Homebrew, the first copy on yourPATH wins. List every copy:
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 <session-id> command from the summary o4 prints when it exits, to continue the same session on the new version.
Models and API keys
Model '<name>' not found
-m doesn’t exist in o4’s model list. Check the spelling, and list the available models:
-m accepts provider:model, provider/model or a bare model ID, for example -m anthropic:claude-sonnet-4-6. Inside a session, /model <name> reports the same problem as Model '<name>' 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 '<name>' is not selectable instead; pass -m or run once without --no-onboarding. See 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.
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.
No default model configured
--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 <provider> 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 providersin o4 and enter the key in the API key row. - Set the provider’s environment variable, such as
ANTHROPIC_API_KEYorOPENAI_API_KEY, before starting o4. A key stored in~/.o4/settings.jsonwins over the variable, so remove a wrong stored key first. - Run
/onboardto go through the setup wizard again.
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:[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 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. /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
autounless you pass--permission-mode, and withaskoraccept-edits, any call that would ask is refused. Pick a different--permission-mode, or add a permission rule. See Permissions. - 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.
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.
Linux: sandbox restrictions require bubblewrap
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:
-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.
Project hooks, MCP servers or settings are ignored
Project configuration only loads in a trusted workspace. Review the repository, then runo4 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.
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.
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. A .o4/harness.toml that isn’t valid TOML is skipped without a log line too; see Harness guides and sensors.
MCP servers
Registry search failed with status 404 Not Found
o4 mcp search and the Registry tab in /mcp show the first error, and o4 mcp add <name> and /mcp add <name> 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.
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). After you fix the config, run /mcp restart <name>. See MCP servers.
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 and Code intelligence.
The terminal display
Colors look wrong or washed out
o4 detects your terminal’s color support fromCOLORTERM 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:
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.
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 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.
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.
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 aslow 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.
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:
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:
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:
/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/<session-id>.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. 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.
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.
Still stuck
Report the problem with/bug from inside o4, or open an issue on the o4 issue tracker. /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.