Codex error messages: what they mean

The Codex error messages people search for most, what each one means and what to do about it. OpenAI's docs have no troubleshooting entry for any of them, so every page quotes the message from the place it can actually be found — Codex's open-source code, or a report on the openai/codex issue tracker — and says which. Where a page rests on a user report, it says so at the top. No cause is stated that a source does not state.

Error messages

Codex stream disconnected: “stream disconnected before completion”

Codex CLI

Codex had a working connection to the model, and the response stream then broke or went quiet before the reply finished. The source comment describes it as the stream disconnecting or erroring out after the HTTP handshake succeeded but before Codex finished receiving the completed response, and it says the session loop treats this as a transient error and automatically retries the turn. The words after the colon are the cause Codex recorded. Two that appear in the source are “stream closed before response.completed” and “idle timeout waiting for SSE”.

Codex 401 Unauthorized: “unexpected status 401 Unauthorized”

Codex CLI, app and IDE extension

Codex builds this line from the HTTP status of a failed request and the body the server sent back, so “401 Unauthorized” is the server's answer and the text after the colon is the server's explanation. The user reports on the tracker show several different explanations behind the same first words: an “Incorrect API key provided” message (#48237), a bare {"detail":"Unauthorized"} (#26497), and “Missing scopes: api.responses.write” (#33664). All three are user reports, so read what follows the colon before deciding which one you have.

Codex command not found: “command not found: codex”

Codex CLI install

The shell is saying it cannot find a program called codex in the places it looks for commands. The “zsh:” at the front is the shell speaking, and neither the docs nor Codex's source has an entry for it. The one issue on the openai/codex tracker with this exact text in its title (#15, from 2025, closed) was from someone who had installed with yarn. The reporter wrote that the cause was a missing npm path in their .zshrc, and a second user who uses asdf wrote that installing with bun worked for them. Those are two users' experiences, and the docs do not cover that case.

Codex could not start: “The extension couldn't load its resources”

Codex IDE extension (VS Code)

In issue #37458 users reported that the Codex panel in VS Code failed to start with “Codex could not start. The extension couldn't load its resources.” On 2026-08-11 a Codex team member (alexr-oai) wrote that “a recent change exposed an existing bug that was previously masked” and that a fix was in progress. On 2026-08-13 the same person announced an update that “fixes the startup watchdog issue”, adding that you should no longer see “The extension couldn’t load its resources” simply because application initialization takes longer than 30 seconds.

Codex model not found: “does not exist or you do not have access to it”

Codex app and CLI

A 404 from the server saying the model you picked is not available to you. In the two tracker reports (#44560 and #43344, both from September 2026) users signed in with a ChatGPT account got it when they chose GPT-5.5, and one wrote “5.6 works.” The text arrived behind “unexpected status 404 Not Found:”, the template Codex uses for failed requests (“unexpected status {status}: {body}”). Codex's current source also has a dedicated case for this: an API error with the code model_not_found and an HTTP status of 400, 403 or 404 is classified as ModelNotFound, shown with the server's own message, and not retried. Both reports are users' own words and neither has a Codex-team answer, only an automated duplicate-finder comment.

Hit a usage limit instead? Check your Codex usage, read usage limits explained, or see whether Codex reset today. Installing for the first time? Install Codex CLI on Mac, Linux, Windows or WSL.