Exact error
Match the message before using the fix
Windows setup didn't finishWindows setup didn't finish • helper_failedCouldn't check Windows setupQuick answer
Start here
Treat this as a summary message, not a root cause. Fully quit Codex, then inspect the newest `.codex\.sandbox\setup_error.json` and sandbox log. Route by the first underlying error: missing helper, JSON parse failure, `SetNamedSecurityInfoW ... 5`, NetFwPolicy2, or a missing UAC launch. Do not reset broad ACLs or disable security software just because the UI says `helper_failed`.
Diagnosis
Why it happens
- Multiple upstream reports show the same UI message for different failures, including no UAC launch, a helper execution failure, corrupt state JSON, and ACL error 5.
- Reinstalling the app does not necessarily clear files under the user's Codex home, so persistent state errors can survive reinstall.
- The UI can hide the structured helper error that is present in `setup_error.json` or the matching sandbox log.
Safest first
Fixes, in order
Capture the underlying setup error
Applies when: Every `Windows setup didn't finish` loop
The correct page depends on the helper's structured error, not the banner.
- Fully quit Codex, including its tray process.
- Copy `.codex\.sandbox\setup_error.json` and the newest sandbox log to a safe diagnostic folder.
- Record the app version, whether UAC appeared, and the first nested error.
- Redact usernames, organization policy, and project paths before sharing logs.
Expected: You have a specific helper or parser error instead of only `helper_failed`.
Check for the confirmed corrupt-state branch
Applies when: The nested error says `expected value at line 1 column 1`, especially after a power loss
One report confirmed a NUL-filled ACL state file and documented regeneration after removing only the corrupt state.
- Back up `deny_read_acl_state.json`, `setup_error.json`, and `config.toml`.
- Verify whether `deny_read_acl_state.json` is empty or filled with NUL bytes.
- Only when that corruption is confirmed, move the corrupt ACL state and setup error out of `.sandbox`.
- Restart Codex and let it regenerate the state; do not remove a healthy `config.toml`.
Expected: The regenerated ACL state is valid JSON and setup proceeds beyond the parse step.
Route every other branch to its exact fix
Applies when: The log names an executable, ACL, COM, credential, or runner error
A broad setup page should not collapse distinct Windows failures into one workaround.
- Use the missing-helper page for `program not found`.
- Use the ACL page for `SetNamedSecurityInfoW failed: 5` or deny-read ACL failures.
- Use the NetFwPolicy2 page for HRESULT 0x80110474.
- If no UAC prompt appears and the log has no nested cause, update the app and report the versioned reproduction.
Expected: The next action matches the exact underlying error and remains reversible.
Verification
Prove the fix worked
- Restart Codex and run Windows setup once.
- Confirm the newest log ends with successful setup/read-ACL completion and no new `setup_error.json` failure.
- Run one harmless command in the normal Windows sandbox.
Escalation
If it still fails
- Do not take ownership of `C:\Users\Default`, WindowsApps, or the entire `.codex` directory.
- Do not delete healthy configuration or sandbox state merely because reinstall did not help.
- Preserve the structured error and app version for the matching upstream report.
Scope
Environment and version notes
- Reports span Codex Desktop builds from July through September 2026, confirming that the same banner covers multiple branches.
- The corrupt-state workaround applies only after confirming an unreadable or NUL-filled file.
- Sources rechecked September 23, 2026.
Evidence
Sources
Source labels describe the evidence available on the checked date. A closed issue is not automatically a shipped fix.