Skip to content

Fixed: share how to fix, Codex GUI failed to launch because it could not initialize its local SQLite state DB. #23848

Open
Open
Fixed: share how to fix, Codex GUI failed to launch because it could not initialize its local SQLite state DB.#23848
Labels
appIssues related to the Codex desktop appbugSomething isn't workingsessionIssues involving session (thread) management, resuming, forking, naming, archivingwindows-osIssues related to Codex on Windows systems

Description

@roccho-dev
roccho-dev
opened on May 21, 2026

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

26.519.2081.0_x64

What subscription do you have?

chatgpt pro

What platform is your computer?

Windows 10 Enterprise

What issue are you seeing?

Summary

Codex GUI failed to launch because it could not initialize its local SQLite state DB.

Screenshot error:

Codex cannot access its local database.
Database path: /mnt/c/Users/<user>/.codex/state_5.sqlite
migration 1 was previously applied but has been modified

Image

Environment

  • OS: Windows 10 Enterprise 10.0.26100.4652
  • Build lab: 26100.1.amd64fre.ge_release.240331-1435
  • Codex app: OpenAI.Codex_26.519.2081.0_x64__2p2nqsd0c76g0
  • WSL: 2.7.3.0
  • WSL kernel: 6.6.114.1-1
  • WSLg: 1.0.73

Likely Cause

Codex GUI had WSL mode enabled:

  • runCodexInWindowsSubsystemForLinux = true
  • active workspace root was under \\wsl$\NixOS\...

Because of that, the Windows Codex home:

C:\Users\<user>\.codex

was accessed from WSL as:

/mnt/c/Users/<user>/.codex

The SQLite state DB then hit a migration mismatch:

migration 1 was previously applied but has been modified

Workaround That Fixed It

  1. Backed up .codex settings.
  2. Disabled GUI WSL mode:
    • runCodexInWindowsSubsystemForLinux = false
    • integratedTerminalShell = powershell
    • active workspace root reset to C:\Users\<user>
  3. Moved these SQLite files out of .codex:
    • state_5.sqlite*
    • logs_2.sqlite*
  4. Restarted Codex GUI.

Codex regenerated the SQLite DBs and launched successfully.

Notes

Please do not ask users to attach full .codex contents, since it may contain auth data and conversation history.

What steps can reproduce the bug?

as above

What is the expected behavior?

No response

Additional information

No response

Activity

  1. roccho-dev
    added
    appIssues related to the Codex desktop app
    on May 21, 2026
  2. github-actions
    added
    bugSomething isn't working
    windows-osIssues related to Codex on Windows systems
    sessionIssues involving session (thread) management, resuming, forking, naming, archiving
    on May 21, 2026

  3. github-actions commented on May 21, 2026

    @github-actions
    github-actionsbot
    on May 21, 2026 – with GitHub Actions
    Contributor

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

    Powered by Codex Action

  4. xdifu commented on May 21, 2026

    @xdifu
    xdifu
    on May 21, 2026

    This is the same root-cause family as #23777 / #23787: the WSL/Linux Codex backend rejects a Windows-created SQLite DB because SQLx migration checksums differ at the CRLF-vs-LF byte level. Moving state_5.sqlite* / logs_2.sqlite* aside is a launch workaround, but it forces Codex to rebuild metadata instead of repairing the existing DBs.

    For users who want to preserve local history metadata, I published a non-destructive repair tool: 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 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 backs up the SQLite DBs, extracts the active backend's expected checksums, schema-verifies before rewriting _sqlx_migrations, and leaves ~/.codex/sessions/*.jsonl read-only.

  5. BadAtCaptchas commented on May 21, 2026

    @BadAtCaptchas
    BadAtCaptchas
    on May 21, 2026

    This is the same root-cause family as #23777 / #23787: the WSL/Linux Codex backend rejects a Windows-created SQLite DB because SQLx migration checksums differ at the CRLF-vs-LF byte level. Moving state_5.sqlite* / logs_2.sqlite* aside is a launch workaround, but it forces Codex to rebuild metadata instead of repairing the existing DBs.

    For users who want to preserve local history metadata, I published a non-destructive repair tool: https://github.com/xdifu/codex-repair

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

    It backs up the SQLite DBs, extracts the active backend's expected checksums, schema-verifies before rewriting _sqlx_migrations, and leaves ~/.codex/sessions/*.jsonl read-only.

    Thank you! Worked like a charm. The update completely broke my Codex install and your tool fixed it.

  6. lantanios commented on May 21, 2026

    @lantanios
    lantanios
    on May 21, 2026

    Revised GitHub Issue Post (with your activism point included)

    Title Suggestion:
    Codex Desktop Crashing on Multiple Windows 11 Systems – Urgent Stability Issues

    Issue Body:

    Description

    I am reporting repeated crashes of Codex Desktop across multiple Windows machines. The issue has now affected three separate systems in quick succession.

    Reproduction Steps / Timeline

    • Two days ago: Installed Codex Desktop on an older Windows 10 laptop → immediate failure.
    • Last night: Codex Desktop on my primary Windows 11 laptop (fully updated, latest WSL + Ubuntu) suddenly crashed and stopped working.
    • This morning: Same crash occurred on another fully updated Windows 11 desktop with latest WSL.

    Environment

    • OS: Windows 11 (latest updates) and Windows 10
    • WSL: Latest version with Ubuntu
    • Codex Desktop: Latest available version

    Additional Context

    It is already disappointing that the macOS version has the “computer use” feature while Windows users still do not. These widespread crashes on Windows now make the situation significantly worse.

    Question for the Codex team: Is anyone actively working on Windows stability issues? Can you confirm if this is a known problem and provide any timeline for resolution?

    Additionally, the growing frustration among Windows users raises a broader concern. Would anyone be interested in organizing a collective effort to advocate for better parity and protection of Windows users’ rights and experience with Codex?

    Image

  7. colinmcdermott commented on May 21, 2026

    @colinmcdermott
    colinmcdermott
    on May 21, 2026

    This is absolutely not fixed

  8. shutupandshave commented on May 22, 2026

    @shutupandshave
    shutupandshave
    on May 22, 2026

    I have this on my mac.

  9. LaZzyMan commented on May 22, 2026

    @LaZzyMan
    LaZzyMan
    on May 22, 2026

    i have this on mac after updateto new version!

  10. crousty24-bit commented on May 22, 2026

    @crousty24-bit
    crousty24-bit
    on May 22, 2026

    This is the same root-cause family as #23777 / #23787: the WSL/Linux Codex backend rejects a Windows-created SQLite DB because SQLx migration checksums differ at the CRLF-vs-LF byte level. Moving state_5.sqlite* / logs_2.sqlite* aside is a launch workaround, but it forces Codex to rebuild metadata instead of repairing the existing DBs.

    For users who want to preserve local history metadata, I published a non-destructive repair tool: https://github.com/xdifu/codex-repair

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

    It backs up the SQLite DBs, extracts the active backend's expected checksums, schema-verifies before rewriting _sqlx_migrations, and leaves ~/.codex/sessions/*.jsonl read-only.

    I confirm it worked just fine. Thank you mate !

  11. ShellaGao commented on May 22, 2026

    @ShellaGao
    ShellaGao
    on May 22, 2026

    i have this on mac after updateto new version!

    absolutely same situation

  12. AnYu798 commented on May 25, 2026

    @AnYu798
    AnYu798
    on May 25, 2026

    Thank you very much, this is very helpful to me.

  13. AZagatti commented on Jul 10, 2026

    @AZagatti
    AZagatti
    on Jul 10, 2026

    If you're on Windows + WSL and Codex Desktop suddenly won't launch with:

    Error: failed to initialize sqlite state runtime under C:\Users\<you>\.codex

    here's what caused it for me and how I fixed it.

    Cause: two different Codex builds were writing to the same database. The Windows app uses C:\Users\<you>\.codex. I had also set CODEX_HOME in my WSL shell to point at that same folder, so the Linux codex binary wrote to it too. The two builds use different DB migrations, so whichever ran last left the database in a state the other can't open. Once the Linux build touched it, the Windows app failed to start.

    Note: the checksum-repair scripts people are sharing didn't help in this case. Those fix drift inside one build. This is two builds with different schemas, so the only real fix is a clean rebuild.

    Fix (chat history is kept):

    1. Fully quit Codex Desktop. Check Task Manager and end any ChatGPT.exe still running.
    2. In C:\Users\<you>\.codex, move these into a backup folder (move, don't delete): state_5.sqlite, logs_2.sqlite, goals_1.sqlite, memories_1.sqlite, including their -wal and -shm files.
    3. Start the app. It rebuilds those databases and re-indexes your history from sessions/*.jsonl.

    If it still fails, one of the four databases is probably still there, or the app wasn't fully closed. All four must be gone and the app fully quit before you relaunch.

    Stop it recurring: don't point WSL's CODEX_HOME at the Windows /mnt/c/.../.codex. Let the Windows app and WSL each keep their own .codex. Sharing one folder to get history in both places is what breaks it.

  14. Shad0wWulf commented on Aug 30, 2026

    @Shad0wWulf
    Shad0wWulf
    on Aug 30, 2026 – with ChatGPT Codex Connector

    Adding a newer recovery result that may help people landing here. I hit the same general Windows Desktop + WSL SQLite startup failure on a much newer build, but was able to recover the existing databases/profile without moving/deleting the state DBs.

    Environment:

    • Codex Desktop 26.825.6671.0
    • Bundled WSL runtime codex-cli 0.151.0-alpha.7.2
    • Windows + WSL2 Ubuntu
    • Shared Codex home at /mnt/c/Users/<user>/.codex

    The app-server failed with the generic:

    failed to initialize sqlite state runtime under /mnt/c/Users/<user>/.codex

    All relevant databases passed PRAGMA quick_check, so I isolated them individually. Existing state_5, goals_1, memories_1, and queue_1 each independently caused startup failure, while thread_history_1 passed.

    Fresh DBs generated by the exact current WSL runtime had matching migration versions/descriptions but different _sqlx_migrations.checksum values. The differences matched the Windows CRLF vs WSL/Linux LF migration-checksum issue discussed in #23777/#32643/#38528.

    The important controlled test was on a disposable copy of the original failing goals_1.sqlite: changing only the _sqlx_migrations.checksum values to those from a fresh DB generated by the current WSL runtime changed the result from FAIL -> PASS. No schema or application data was rebuilt.

    After taking a full backup, I applied the same checksum-only repair to the affected real state_5, goals_1, memories_1, and queue_1 databases. The original real profile then initialized successfully in WSL and Codex Desktop resumed normal operation, including real turns, WSL shell commands, file writes/deletes, and Desktop diffs.

    So for users who need to preserve their existing state, deleting/moving the SQLite DBs is not necessarily required when the failure is specifically this migration checksum incompatibility. Back up the entire .codex directory first, and verify that the migration versions/descriptions are identical before considering any checksum repair. Do not blindly rewrite migration metadata for unrelated SQLite failures.

    More detailed findings were also posted on #38528.

    This comment was written with assistance from ChatGPT after an interactive diagnostic session; the commands, outputs, A/B tests, and final recovery were run and verified on the affected machine by the user.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    appIssues related to the Codex desktop appbugSomething isn't workingsessionIssues involving session (thread) management, resuming, forking, naming, archivingwindows-osIssues related to Codex on Windows systems

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions