xdifu

xdifu / codex-repair

Public

Fix "Codex cannot access its local database" / "migration 1 was previously applied but has been modified" / "timed out waiting for state db backfill after 30s" on Codex Desktop (Windows/WSL/Mac/Linux) after the 0.130 → 0.131 update. CRLF/LF sqlx checksum drift in state_5.sqlite + logs_2.sqlite. Sessions preserved. See openai/codex#23787.

backfill chatgpt chatgpt-pro checksum-mismatch codex
10
1
89% credibility
Found May 21, 2026 at 10 stars -- GitGems finds repos before they trend. Get early access to the next one.
Sign Up Free
AI Analysis
Python
AI Summary

The Codex Repair Toolkit is a community-created open-source tool that fixes a specific crash affecting Codex Desktop users after an automatic update from version 0.130 to 0.131. The crash occurs because of two bugs: a database migration checksum mismatch caused by different line endings between Windows and Linux code, and a 30-second timeout that's too short for large conversation histories. The toolkit diagnoses these issues without touching anything, then safely repairs them with automatic backups, schema verification, and dry-run options. Your actual conversation history is never modified — only the internal bookkeeping databases are touched.

How It Works

1
💥 Codex crashes after updating

Your Codex Desktop app suddenly won't start, showing an error about not being able to access its local database.

2
🔍 You search for a fix and find this toolkit

You discover that this is a known bug affecting many users after the automatic update, and this toolkit was created to fix it.

3
🩺 You run the diagnostic to check your system

With one simple command, the tool scans your Codex installation and tells you exactly what's wrong — without changing anything.

4
Two paths emerge
✅
System is healthy

Everything looks good — no action needed, your Codex should work normally.

⚠️
Issues found

The tool detected migration checksum mismatches and possibly stuck background indexing that need repair.

5
🔧 You apply the repair

The tool automatically fixes the mismatched checksums and completes the background indexing, all while keeping backups of your data.

🎉 Codex works again, your conversations are safe

Your app launches successfully, all your chat history is preserved, and everything works exactly as before.

Sign up to see the full architecture

4 more

Sign Up Free

Star Growth

See how this repo grew from 10 to 10 stars Sign Up Free
Repurpose This Repo

Repurpose is a Pro feature

Generate ready-to-use prompts for X threads, LinkedIn posts, blog posts, YouTube scripts, and more -- with full repo context baked in.

Unlock Repurpose
AI-Generated Review

What is codex-repair?

codex-repair is a Python toolkit that fixes a specific crash affecting Codex Desktop users after the 0.130 to 0.131 auto-update. The update triggers two bugs: a SQLite checksum mismatch because the Windows backend switched to a WSL binary with different line endings, and a 30-second backfill timeout that fails on large session histories. The tool runs as a CLI with subcommands like `doctor` (read-only diagnosis), `fix` (auto-repair with dry-run by default), and `extract-checksums` (dumps expected migration hashes). It scans the backend binary directly, verifies schema compatibility before touching anything, and backs up databases before mutating them. Sessions are never touched.

Why is it gaining traction?

The hook is specificity. This fixes a known OpenAI bug that broke Codex for thousands of users with no workaround until now. The tool auto-detects the backend binary, extracts embedded migration checksums from it, compares against the actual database records, and applies targeted fixes only when the schema is already compatible. It handles both affected databases (state_5.sqlite and logs_2.sqlite) in one pass. Safety defaults mean you can run diagnosis against a running Codex without data loss.

Who should use this?

If you updated Codex Desktop and see "Codex cannot access its local database" or "timed out waiting for state db backfill after 30s," this is your fix. It works on Windows with WSL, macOS, and Linux. Windows users on the Store version are the primary affected group given the CRLF/LF root cause.

Verdict

The tool is well-documented and the safety model is solid (dry-run default, backups, schema verification). At 10 stars, it is early-stage, but the active upstream issue tracking means the root cause is understood and the approach is sound. Recommend trying `codex-repair.py doctor` first if you hit this error. The 0.8999999761581421% credibility score reflects active maintenance and clear attribution to a real incident.

Sign up to read the full AI review Sign Up Free

Similar repos coming soon.