codex - 💡(How to fix) Fix Bug: Codex Desktop fails after enabling WSL

What version of the Codex App are you using (From “About Codex” dialog)?

26.519.22136

What subscription do you have?

Plus

What platform is your computer?

Microsoft Windows NT 10.0.26200.0 x64

What issue are you seeing?

After enabling WSL mode in Codex Desktop and restarting the app, Codex fails to start because it cannot access its local SQLite database.

Full error message with PII redacted:

Codex cannot access its local database.

The app cannot finish launching until its SQLite database is accessible.

Database path: Path unavailable in app-server startup error

Error: (code=1, signal=null). Most recent error: Error: failed to initialize sqlite state runtime under /mnt/c/Users/<user>/.codex: failed to initialize state runtime at /mnt/c/Users/<user>/.codex: migration 1 was previously applied but has been modified

I did a preliminary investigation and found that the SQLite database itself does not appear to be corrupted. PRAGMA integrity_check returns ok.

The issue appears to be a SQLx migration checksum mismatch between the Windows Codex runtime and the WSL/Linux Codex runtime while sharing the same CODEX_HOME.

<img width="691" height="364" alt="Image" src="https://github.com/user-attachments/assets/b1d724ad-c152-41a6-a325-bc2df0de3873" />

What steps can reproduce the bug?

1. Delete or rename the existing Codex home directory: C:\Users<user>.codex

2. Start Codex Desktop on Windows.

3. Let Codex complete initial startup/onboarding.

4. Codex creates: C:\Users<user>.codex\state_5.sqlite

5. Enable WSL mode in Codex Desktop settings.

6. Restart Codex Desktop.

7. Codex attempts to start the runtime under: /mnt/c/Users/<user>/.codex

8. Startup fails with: migration 1 was previously applied but has been modified

No code snippet is required to reproduce this; it is caused by the Desktop + WSL runtime initialization flow.

Session id / token usage / context window usage: not applicable.

What is the expected behavior?

After enabling WSL mode and restarting Codex Desktop, the app should start normally.

Codex should either:

• use migration files with identical checksums across Windows and WSL builds;
• avoid creating a Windows-initialized state_5.sqlite before switching to WSL;
• use a separate WSL-compatible state database/CODEX_HOME;
• or provide a safe migration/repair path when switching from Windows runtime to WSL runtime.

A newly initialized Codex home should not become unusable immediately after enabling WSL mode.

Additional information

I performed a preliminary investigation and can attach a detailed Markdown report.

Key findings:

• The SQLite databases pass PRAGMA integrity_check = ok.
• The failure is in SQLx migration validation, not SQLite corruption.
• Windows-created state_5.sqlite contains migration 1 checksum: 54BBD6F4...
• WSL/Linux-created state_5.sqlite contains migration 1 checksum: 627EF191...
• The embedded migration SQL in the Windows binary appears to use CRLF line endings (\r\n).
• The embedded migration SQL in the WSL/Linux binary appears to use LF line endings (\n).
• SQLx appears to hash the raw migration bytes, so the same logical migration gets different checksums across runtimes.
• The WSL runtime then opens the Windows-created database from: /mnt/c/Users/<user>/.codex and fails because the checksum stored in _sqlx_migrations does not match the WSL runtime’s embedded migration checksum.

This looks like a cross-runtime migration checksum incompatibility combined with shared state path and Windows-first initialization order.

codex-wsl-sqlite-migration-analysis-en.md