Community Codex Windows Troubleshooting Field Guide

June 10, 2026 · View on GitHub

Community-maintained diagnostics, issue mapping, and safe workarounds for Codex on Windows.

简体中文 · Error Guide · Report A Case · Run Diagnostics · Contribute

Unofficial project. This repository is not affiliated with, endorsed by, or sponsored by OpenAI. See Branding and Naming.

One-Line Summary

This GitHub project helps Codex users on Windows diagnose common failures, map them to verified upstream issues, and apply safe troubleshooting steps without guessing.

Quick Actions

I want to...	Start here
Fix a Codex Windows error	Search the exact error in Windows Codex Error Guide
Share a new failure	Open a redacted case report
Add an upstream issue or community source	Submit a source lead
Validate a workaround	Follow the contribution rules

Codex on Windows can fail in ways that are hard to classify from the UI alone: worktree creation errors, Windows sandbox startup failures, Browser or Computer Use plugin issues, WSL path split-brain, PowerShell quirks, session crashes, and Microsoft Store packaging edge cases.

This project turns scattered GitHub issues and community reports into a verified field guide:

error signatures you can search for
evidence levels for each claim
safe first checks before destructive fixes
known GitHub issue mappings
dogfood coverage for every major case in the guide
read-only diagnostic scripts for local investigation

Quick Start

If you hit a Codex Windows error, start here:

Search the exact error text in Windows Codex Error Guide.
Check the case coverage in Dogfood Matrix.
Run the read-only diagnostics script from PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File ".\skills\codex-windows-troubleshooter\scripts\collect-codex-windows-diagnostics.ps1" -Workspace "<YOUR_REPO>"

Review the output before posting it publicly.

Contribute A Case

Raw reports are welcome. You do not need to write a pull request or understand the whole guide to contribute. Maintainers will normalize useful reports into case IDs, guide updates, dogfood rows, and skill/reference updates.

The fastest useful report is:

Error:
Surface: Windows app / CLI / WSL / Browser / Computer Use / Store / winget
Windows:
Codex version:
What happened:
What fixed it, if anything:
Related links:

Use one of these paths:

Path	Best for	Start here
Error report	You have an exact error message or screenshot text	Open a redacted case report
Upstream mapping	You found a relevant `openai/codex` issue, Reddit, V2EX, X, blog, or other source	Add source context
Verified fix	You tested a workaround or version boundary safely	Submit a pull request
Guide correction	A section is wrong, stale, or too risky	Contributing rules

Please include the exact error text, Codex surface, Windows version family, Codex version if available, reproduction status, related links, and workaround status. Redact tokens, private repo names, personal paths, screenshots with personal data, and full .codex session files.

Data Flywheel

Each useful contribution should become reusable data, not a one-off support thread:

Raw report -> normalized error signature -> case ID -> guide update -> dogfood check -> skill/reference update

Maintainers can do the normalization work. Contributors only need to provide redacted facts: exact error text, environment family, what they tried, and links to upstream/community evidence.

Top Errors

Error signature	Likely family	Start here
`fatal: invalid reference: master`	Git worktree / unborn branch / missing local ref	Worktree creation failed
`fatal: invalid reference: main`	Git worktree / repo without local `main`	Worktree creation failed
`Computer Use plugins unavailable`	Bundled plugin marketplace / helper paths	Computer Use / Browser plugins
`No plugins found in marketplace openai-bundled`	Bundled marketplace cache	Computer Use / Browser plugins
`SetIsBorderRequired failed: 0x80004002`	Windows 10 Computer Use screenshot API	Windows 10 Computer Use
`windows sandbox failed: spawn setup refresh`	Windows sandbox helper startup	sandbox setup refresh
`The requested operation requires elevation. (os error 740)`	UAC / sandbox setup helper	os error 740
`CreateProcessWithLogonW failed`	Windows sandbox user startup	other sandbox startup errors
`SetTokenInformation(TokenDefaultDacl) failed: 1344`	Windows sandbox DACL edge case	other sandbox startup errors
`RangeError: Invalid string length`	oversized session / rollout JSONL	large sessions and crashes

Covered Error Families

fatal: invalid reference: master/main/feature during Codex worktree creation
Computer Use plugins unavailable
No plugins found in marketplace openai-bundled
SetIsBorderRequired failed: 0x80004002
windows sandbox failed: spawn setup refresh
The requested operation requires elevation. (os error 740)
CreateProcessWithLogonW failed
SetTokenInformation(TokenDefaultDacl) failed: 1344
sandbox DNS/npm/proxy failures
WSL and Windows CODEX_HOME split-brain
PowerShell execution, path, and encoding issues
RangeError: Invalid string length
corrupted config.toml
blank startup windows and Crashpad dumps
antivirus and enterprise security software blocks
Microsoft Store install path and ARM64 edge cases

Evidence Levels

A: official documentation or official engineering posts
B: reproducible openai/codex GitHub issues plus system behavior
C: community posts, blogs, Reddit, V2EX, X, or Xiaohongshu
D: engineering inference that still needs reproduction

Workarounds are not treated as solved unless they have repeatable verification or a confirmed version boundary.

Project Files

CodexGuide: a broader Codex learning and practice guide for beginners, creators, developers, and teams. Use it for onboarding, workflow design, configuration, and general Codex usage.

This repository stays focused on Codex-on-Windows failures, diagnostics, evidence levels, and safe troubleshooting. If your question is not Windows-specific, CodexGuide is usually the better starting point.

Contributing

Start with Contribute A Case or see CONTRIBUTING.md for redaction, evidence, dogfood, and pull request rules.

License

MIT. See LICENSE.