WSL agent environment corrupts local state_5.sqlite migration on Windows

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #23824
• #23777
• #23251
• #23787

Powered by Codex Action

same problem
any fixes?

Deleting the .codex directory and restarting Codex fixed the startup issue for me, but it also wiped all local chat history.

At the moment I don't know a way to recover/fix the migration issue while preserving the existing chat history database.

but deleting .codex directory changes WSL to Windows Native as well

You're right. I forgot to mention that.

Deleting the .codex directory also reset the agent environment setting from WSL back to Windows Native. But to be clear, that was just a workaround to get it launching again, not a proper fix for the underlying issue.

when i perform an app refresh on a fresh .codex directory to allow wsl again it crash again with the same issue

same issue

when i perform an app refresh on a fresh .codex directory to allow wsl again it crash again with the same issue

yeah. same

I may have found a temporary workaround.

First, install the Codex CLI package wsl side:

# Using npm
npm install -g @openai/codex

# Using Homebrew
brew install --cask codex

Then set the CODEX_HOME environment variable so it points to the Windows .codex directory and run codex CODEX_HOME=/mnt/c/Users/username/.codex codex

Codex should detect the corrupted database and repair it.

<img width="1396" height="215" alt="Image" src="https://github.com/user-attachments/assets/fc8efdfd-04b9-46e6-a483-fe5959a90e87" />

Once the repair is complete, the Codex app should be able to run with WSL support again.

Then set the CODEX_HOME environment variable so it points to the Windows .codex directory: export CODEX_HOME=/mnt/c/Users/username/.codex restart the terminal then run codex

@sabruss it works, thx.
btw, we can run CODEX_HOME=/mnt/c/Users/username/.codex codex in one line to avoid the restarting.

thank you. it works.

Technical Solution for WSL State Corruption

Root Cause

NOT actual database corruption — it is a CRLF/LF line ending mismatch in SQLx migration checksums:

• Windows binaries embed SQL migration files with CRLF (\r\n) line endings
• WSL/Linux binaries embed the same SQL files with LF (\n) line endings
• SQLx validates migrations using byte-for-byte SHA-384 checksums, so sha384(CRLF) != sha384(LF)
• When a user switches from Windows Native to WSL agent mode, the WSL binary rejects the database

Proposed Fix (4-part)

1. Build-time normalization — .gitattributes + normalize_migration_sql() to ensure consistent line endings
2. Automatic checksum repair on startup — recovers affected users without data loss
3. Graceful error with recovery instructions — defensive UX improvement
4. Per-environment DB separation — optional architectural improvement

Code Changes

• .gitattributes: Add * text=auto eol=lf for SQL files
• crates/codex-sqlx/src/migration.rs: Add normalize_migration_sql() + checksum repair
• crates/codex-app/src/db.rs: Add per-environment DB path

Test Plan

• Unit: Verify line ending normalization
• Integration: Switch between Windows/WSL, verify DB compatibility
• Manual: Reproduce original issue, verify recovery

Impact

• Severity: CRITICAL — data corruption for WSL users
• Risk: LOW — fix is additive, backward compatible
• Estimated Value: $2,000–$3,000

Full solution: solutions/codex-23841-wsl-agent-corrupts-state-sqlite-fix.md

This looks like the same CRLF/LF SQLx checksum mismatch tracked in #23777 and #23787. Switching a Windows-created CODEX_HOME to the WSL backend can make the Linux binary expect LF-hashed migrations while the existing SQLite DB has CRLF-hashed _sqlx_migrations rows. Deleting .codex gets the app launching again, but it loses the existing local history metadata.

For a non-destructive recovery path, I published a small Apache-2.0 toolkit here: https://github.com/xdifu/codex-repair

Windows PowerShell / Windows Terminal:

git clone https://github.com/xdifu/codex-repair.git
cd codex-repair
python codex-repair.py doctor
python codex-repair.py fix --apply

If you run it from WSL bash to repair Windows Codex Desktop data, pass --codex-home "/mnt/c/Users/<WindowsUser>/.codex" so it does not target WSL's own ~/.codex.

It extracts the expected checksums from the active Codex backend binary, schema-verifies before any write, backs up state_5.sqlite / logs_2.sqlite, and can also finish the state backfill outside the 30s GUI timeout. sessions/*.jsonl stays read-only.

it's actually logs_2.sqlite
solved here:
https://github.com/openai/codex/issues/23863