Bootstrap guide
Codex Startup and TUI Bootstrap Errors
Route Codex account/read, configRequirements/read, app-server handshake, SQLite, sandbox, and plugin startup errors by their nested cause.
Match the complete nested error, client surface, operating system, and version. Similar outer messages can hide different failures.
Safety boundary: do not delete `.codex`, invent a missing managed requirements file, or cycle credentials repeatedly before identifying the nested error.
Choose by stage
Account and configuration bootstrap
The outer bootstrap message is not enough; keep the nested JSON-RPC text and code.
account/read failed during TUI bootstrap
Error: account/read failed during TUI bootstrapDiagnose Codex CLI account/read startup failures by the nested error instead of treating every case as a login problem.
Open exact fix →configRequirements/read fails with No file descriptors available
configRequirements/read failed during TUI bootstrapDiagnose Codex TUI bootstrap when app-server file-descriptor exhaustion is mislabeled as a requirements-file error.
Open exact fix →Codex config.toml missing escaped value on Windows
failed to reload config: missing escaped value, expected `b`, `e`, `f`, `n`, `r`, `\`, `"`, `x`, `u`, `U`Fix Codex config.toml missing escaped value on Windows by using valid TOML paths with forward slashes or literal strings.
Open exact fix →Choose by stage
App-server and local state
Use these when the backend handshake or local state store fails before the first prompt.
Codex app-server initialize handshake times out in WSL mode
Codex app-server initialize handshake timed outDiagnose Codex Desktop WSL startup when the app-server initialize handshake times out and nested logs show bwrap relocation ENOENT.
Open exact fix →Codex Desktop SQLite pool times out during startup
Codex cannot access its local databaseRecover Codex Desktop when logs_2.sqlite grows large and startup fails with pool timed out while waiting for an open connection.
Open exact fix →thread history projection expected ordinal N, got N-1
thread-store internal error: thread history projection ... expected ordinal 192591, got 192590 (code -32603)Recover safely when a long Codex thread cannot fork or resume because its thread-history projection ordinal is out of sync.
Open exact fix →Choose by stage
Sandbox and bundled integration startup
Use these when startup stops inside bwrap, the Windows helper, or bundled MCP initialization.
bwrap cannot create the Codex synthetic mount directory in /tmp
bwrap: Can't mkdir /tmp/codex-bwrap-synthetic-mount-targets-1000: Read-only file systemDiagnose Codex startup when a managed Linux permission profile denies /tmp before the sandbox helper can create its mount directory.
Open exact fix →Windows setup didn't finish: helper_failed
Windows setup didn't finishRoute the Codex Windows setup loop to its real helper, ACL, state-file, or UAC branch before changing system permissions.
Open exact fix →Codex bundled MCP fails with JSON-RPC error -32603
MCP startup failed: handshaking with MCP server failed: JSON-RPC error: -32603Diagnose Messages and Computer History MCP startup failures caused by an experimental capability compatibility mismatch.
Open exact fix →