wikis / Codex / wiki / summaries / casebook-runtime.md view as markdown

Casebook: Runtime Errors — Streams, Hangs, Approvals, Routing

Solved-problem casebook from openai/codex GitHub issues: symptom (verbatim) → cause → fix/workaround → issue ref. Ordered diagnosis lives in troubleshooting checklist; auth-shaped errors live in casebook auth limits.

Key Points

A. "stream disconnected before completion" family

Case A1 — context window exceeded (retry loop, then hard fail)

• Symptom (verbatim): ⚠️ stream error: stream disconnected before completion: Your input exceeds the context window of this model. Please adjust your input and try again.; retrying 1/5 in 208ms… … ■ stream disconnected before completion: ...
• Cause: session context genuinely too large (long thread, big diffs/screenshots).
• Fix: run /compact; if /compact itself fails, start a new chat/session. — Issue #3924.

Case A2 — Transport error: error decoding response body

• Symptom (verbatim): ⚠️ stream error: stream disconnected before completion: Transport error: error decoding response body; retrying 1/5 in 181ms…
• Cause: mix of client bug (largely fixed in 0.39.0), VPN/proxy interference, server-side incidents, and running multiple concurrent CLI processes (only one streams, others fail).
• Fix/workaround: update the CLI; disable/rotate VPN or proxy; reduce concurrent Codex processes; if widespread the same day, assume a service incident and retry later. — Issues #3835, #8302.

Case A3 — remote compact task fails

• Symptom: Error running remote compact task: stream disconnected before completion (often on long threads, subagent-heavy threads, or threads containing screenshots); endpoint https://chatgpt.com/backend-api/codex/responses/compact.
• Workaround (verbatim commands):

  codex resume <session-id> --disable enable_request_compression --no-alt-screen
  codex fork <session-id> --disable enable_request_compression --no-alt-screen
  

• — Issue #9544.

Case A4 — fails on the very first message (stream closed before response.completed)

• Symptom (verbatim): stream error: stream disconnected before completion: stream closed before response.completed; retrying 1/10 in 191ms…
• Cause: triggered by the internally generated API-key creation request on fresh accounts/orgs, not the user prompt (historical, v0.3.0 era).
• Fix: ensure the org has a working API key / use an established org; update the CLI. — Issue #1481.

B. Hangs

Case B1 — CLI hangs indefinitely on all prompts

• Symptom: prompt accepted, no streaming output, no error, status bar stuck at "100% left"; response eventually arrives after ~5 minutes. Happens "predominantly right around forced compaction time (10–20% context left)"; codex fork on the long thread also stalls.
• Cause: suspected server-side compaction stall; new chats respond instantly.
• Workaround: run /compact manually before context drops below ~20%; otherwise start a new thread. Downgrading did not help (not a client regression). — Issue #14048.

Case B2 — hangs during shell command execution

• Symptom: Codex does half the job then sticks during terminal command execution; many users simultaneously.
• Cause: service incident (not visible on the status page at the time).
• Workaround: switch model (e.g. gpt-5.1-codex instead of -max) or wait out the incident. — Issue #7156.

C. Approval-prompt spam

Case C1 — Linux/bwrap: approval prompt for almost every command

• Symptom (verbatim): approval prompts for find, ls, sed despite "Yes, and don't ask again"; sandbox error: exec_command failed ... stderr: "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted.
• Cause: Ubuntu 24.04+ AppArmor restricts unprivileged user namespaces, so bubblewrap fails and Codex silently falls back from workspace-write to read-only — every write needs approval. Surfaced on CLI 0.115.0.
• Fixes (in order of preference):
  1. Load the packaged AppArmor profile (see sandboxing approvals): sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict (after installing apparmor-profiles).
  2. Per-binary AppArmor profile for the resolved codex path (readlink -f "$(command -v codex)") with flags=(default_allow) { userns, }, then sudo apparmor_parser -r /etc/apparmor.d/codex-userns — avoids the system-wide off switch.
  3. Blunt: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 (weakens kernel hardening).
  4. Downgrade to codex-cli 0.114.0 (temporary). — Issue #14936.

Case C2 — Windows: permission ask for every PowerShell command (historical)

• Symptom: every operation prefixed powershell -NoProfile -Command ... requires approval; "Full Auto"//approvals had no effect; PowerShell quoting failures forced double approvals (Missing closing ')' in expression.).
• Cause: early Windows support (CLI 0.25–0.27) predated the native Windows sandbox.
• Workaround then: --yolo (dangerous) or VS Code "Agent (full access)". Today: use the native Windows sandbox in PowerShell or WSL2 per sandboxing approvals; see also sandbox approval guide. — Issue #2860.

Case C3 — macOS app: stuck "Awaiting approval" that can't be approved

• Symptom: approval prompt highlights selection but Yes/submit do nothing; a stale past approval blocks a new one.
• Cause: app UI bug on long-running sessions; no repro identified.
• Workaround: fully quit and restart the Codex app (switching threads does not help); resend the last message. — Issue #10760. Unresolved at fetch time.

D. Model routing, GPU, undo, misc

Case D1 — gpt-5.3-codex silently routed to gpt-5.2

• Symptom: config and TUI say gpt-5.3-codex but response.created reports gpt-5.2-2025-12-11. Verbatim detection one-liner:

  RUST_LOG='codex_api::sse::responses=trace' codex exec --sandbox read-only --model gpt-5.3-codex 'ping' 2>&1 \
    | grep -m1 'SSE event: {"type":"response.created"' \
    | sed 's/^.*SSE event: //' | jq -r '.response.model'
  

• Cause: account-specific server-side routing (same command on a work account returned gpt-5.3-codex).
• Workaround: verify with the command above; report with /feedback thread ID. No client-side fix. — Issue #11189.

Case D2 — Codex app uses 70–90% GPU on macOS

• Symptom: Electron process at 70–90% GPU, high temperatures; sluggish UI, slow thread switching; reported on M1 Pro through M3 Max/M4 Pro.
• Suspected cause: diff view failing to release GPU resources after viewing large diffs ("usage pattern only started after I opened that section").
• Workaround: avoid keeping large diff views open; restart the app; submit /feedback. Maintainers investigating ("reports of large diffs resulting in poor performance"). — Issue #10432.

Case D3 — Undo/"Changes reverted" doesn't revert (VS Code extension)

• Symptom: green toast "Changes reverted" but the file is unchanged; on other versions a red toast Failed to revert changes.
• Cause: revert path depends on Git: in a Git repo the underlying file is reverted (the open diff view just doesn't refresh); in a non-Git folder revert fails outright.
• Fix/workaround: check the file on disk, not the diff view; keep projects under Git for working undo; otherwise ask the agent to revert. — Issue #3567.

Case D4 — invalid_encrypted_content error

• Symptom (verbatim): {"error": {"message": "The encrypted content gAAA...5f0= could not be verified.", "type": "invalid_request_error", "code": "invalid_encrypted_content"}} — repeats on "continue".
• Cause: server-side incident (maintainer: "We're aware of the problem"); hit big-context tasks across CLI and extension simultaneously; logout/reinstall did not help.
• Workaround: wait out the incident; small tasks still worked; web Codex unaffected. — Issue #8120.

Case D5 — uv / Python tooling fails under the sandbox

• Symptom (verbatim): error: failed to open file /Users/.../Library/Caches/uv/sdists-v9/.git: Operation not permitted (os error 1) and pyenv: cannot rehash: ... shims isn't writable.
• Cause: uv's cache (with embedded .git dirs, implicitly read-only) lives outside the workspace; workspace-write blocks it.
• Workarounds: set UV_CACHE_DIR inside the repo; or add writable roots (verbatim):

  [sandbox_workspace_write]
  writable_roots = [
      "/Users/my_user/.cache/uv",
      "/Users/my_user/.cache/pre-commit",
      "~/Library/Caches/mise",
  ]
  

  Note: users reported writable_roots ineffective for the .git-embedded cache paths on some versions; danger-full-access worked but is a blunt instrument. — Issue #1457. See sandbox approval guide.

E. Worktrees & Handoff (app)

Case E1 — "Hand off" missing on worktree threads (regression; docs not updated)

• Symptom: worktree threads show no Hand off control anywhere (thread header, command menu) — only Create branch appears. The documented worktree→Local handoff flow is unavailable.
• Cause: UI regression after an app update; affects new and pre-existing worktree threads; reported on macOS (app 26.305.950) and field-confirmed on Windows 2026-06-11. Issue closed without visible resolution; docs still describe the old workflow.
• Workarounds (field-verified): commit in the worktree, then from the local checkout git merge <branch> (merging works even while the branch is checked out in the worktree — Git only forbids double checkout); branch-less variant: git rev-parse HEAD in the worktree → git merge <sha> locally; to check the branch out locally: git switch --detach in the worktree first, then git switch <branch> locally. Reminder: Create branch here names the branch but does not commit — commit before merging or pushing. — Issue #14141.

Case E2 — Windows handoff doesn't merge back (when present)

• Symptom: on Windows builds that still had the button (26.313.5234.0 Msix), Handoff converted the worktree into a local branch but did not offer the merge-back flow shown in macOS demos; master unchanged, manual merge required.
• Cause: platform inconsistency vs the macOS handoff flow; no maintainer response.
• Workaround: manual merge/cherry-pick of the worktree branch (see E1). — Issue #15314. Open at fetch time.

Relevant Concepts

• sandboxing approvals — the mechanism behind cases C1–C2, D5
• sandbox approval guide — recommended mode/policy combos
• troubleshooting checklist — ordered diagnosis using these cases
• release digest — version-specific regressions and fixes

Source Metadata

• Type: GitHub issues from openai/codex (#3924, #3835, #8302, #9544, #1481, #14048, #7156, #14936, #2860, #10760, #11189, #10432, #3567, #8120, #1457), fetched 2026-06-10; #14141 and #15314 fetched live 2026-06-11 with field verification on Windows (see field notes windows app).
• Confidence: medium (community-reported); C1 cause and A2 partial fix corroborated by maintainers/docs; C3, D1, D2 unresolved at fetch time (lower); E1 workarounds field-verified end-to-end (higher), E1/E2 underlying fix status unknown.