Exact error
Match the message before using the fix
Codex app-server initialize handshake timed outInitialize handshake still pending durationMs=30002bundled_executable_relocation_failed failedExecutableName=bwrap errorCode=ENOENTQuick answer
Start here
The handshake timeout is an outer symptom, so read the lines immediately before it. In the verified report, the exact app-server command worked manually and SQLite checks passed, while Desktop logged a WSL Codex-home fallback and `bundled_executable_relocation_failed` for `bwrap` with ENOENT. Updating and restarting is safest first. If you need the app immediately, switching WSL mode off let native Windows mode start, but WSL-backed conversations became unavailable; treat that as a reversible bypass, not a repair.
Diagnosis
Why it happens
- Desktop waits about 30 seconds for the app-server initialize response and reports only the outer timeout.
- The source report's earlier log lines show WSL Codex home resolution fallback and failure to relocate the bundled `bwrap` executable.
- Database locks, a slow logs database, and other app-server failures can produce the same outer handshake message, so the nested log determines the branch.
Safest first
Fixes, in order
Read the nested startup error before changing WSL
Applies when: Every app-server initialize handshake timeout
The outer 30-second message does not identify whether executable relocation, home resolution, SQLite, or another startup stage failed.
- Record the Codex Desktop version, WSL distribution, and WSL-mode setting.
- Open the Desktop startup log and locate the 30 seconds before the handshake timeout.
- Search for `bundled_executable_relocation_failed`, `bwrap`, `CODEX_HOME`, SQLite pool errors, or a process exit code.
- Follow only the branch that appears in your log.
Expected: You have a specific nested failure rather than only the generic handshake timeout.
Update and rebuild the WSL helper state through the official app
Applies when: The exact bwrap ENOENT or WSL home-resolution branch
The issue was closed without documenting a fixed build, so avoid downloading or copying helper binaries manually.
- Update Codex Desktop through its normal official channel.
- Fully quit Desktop and stop only its orphaned app-server processes.
- Start WSL normally and confirm the selected distribution launches.
- Restart Desktop in WSL mode and capture the new relocation log.
Expected: Desktop resolves its WSL home and bundled executable, or cleanly reproduces the closed issue on the current build.
Use native Windows mode as a reversible bypass
Applies when: When the exact WSL startup path is blocked and native mode is acceptable
The reporter confirmed `runCodexInWindowsSubsystemForLinux = false` allowed startup, but WSL-backed conversation access was lost.
- Back up the current configuration and note the WSL distribution in use.
- Disable the run-in-WSL setting through the supported Desktop preference.
- Restart Desktop and use a native Windows project for the bounded task.
- Restore WSL mode after a fixed build or after collecting diagnostics.
Expected: Desktop starts in native Windows mode, with the WSL conversation-access tradeoff understood.
Verification
Prove the fix worked
- Restart Desktop in the intended execution mode.
- Confirm the initialize handshake completes instead of remaining pending for 30 seconds.
- Open an appropriate native or WSL-backed conversation and run a harmless command.
Escalation
If it still fails
- Capture the complete nested log, not only `initialize handshake timed out`.
- If the nested error is a SQLite pool timeout, use the targeted logs database recovery page instead.
- Do not download `bwrap` or bundled helpers from unofficial sources or copy them between versions.
Scope
Environment and version notes
- The detailed report used Desktop 26.814.5167.0, Windows 11, WSL2 Fedora, and Codex CLI 0.148 alpha.
- The issue was closed without a cited shipped fixed version as of August 20, 2026.
- Sources rechecked August 20, 2026.
Evidence
Sources
Source labels describe the evidence available on the checked date. A closed issue is not automatically a shipped fix.