Fix Codex App database is locked in WSL mode: cause and workarounds¶

For / Key Points

For: Developers using the Windows Codex App with WSL2 who see database is locked during startup.

Key Points:

If the error path starts with \\wsl.localhost\..., inspect the Windows/WSL boundary before repairing SQLite
Codex App 26.609.4994.0 has an open startup failure issue in the official repository
Disabling WSL mode and switching back to PowerShell can make the app launch again

When Codex App fails at launch with database is locked, the obvious first theory is a broken SQLite file or a stale process. In WSL mode, that theory can be wrong. The practical question is: should this error be treated as a local database repair task, or as a Windows/WSL integration failure?

As of June 13, 2026, the openai/codex repository has an open issue for Windows Codex App 26.609.4994.0 no longer opening after an update¹. There are also related issues around WSL mode, Windows-side app-server launch behavior, and local SQLite state DB failures²³⁴. The safe response is to triage without deleting useful state first.

Fastest recovery when the app will not open¶

Even if the desktop app will not open at all, disabling WSL mode can make Codex App launch again. This is a Windows-native bypass, not a fix for the broken WSL path. The recovery path was confirmed on a real machine on June 14, 2026.

If your active workspace is already on the Windows side, this workaround has a smaller operational cost. The usual Codex App home is C:\Users\<User>\AppData\Local\OpenAI\CodexAppHome. There is no need to publish the real username or full local path in a bug report.

Try the config-only recovery first.

Fully quit Codex App, including any remaining Codex-related processes in Task Manager
Back up CodexAppHome\config.toml, then set [desktop] as shown below
Launch Codex App again

[desktop]
runCodexInWindowsSubsystemForLinux = false
integratedTerminalShell = "powershell"

If the app opens, do not regenerate the database. Only move state_5.sqlite* and logs_2.sqlite* aside if the app still fails after the config change. If that also fails, treat the situation as a build-specific app problem and consider rollback or waiting for a fixed release.

Symptom: database is locked plus a WSL UNC path¶

The first string to inspect is not only database is locked. Look at the database path printed immediately before it.

A typical error shape looks like this.

Codex cannot access its local database.
failed to initialize sqlite state runtime under
\\wsl.localhost\<Distro>\home\<user>\.codex-app:
error returned from database: (code: 5) database is locked

\\wsl.localhost\... means a Windows-side process is looking at the WSL filesystem through a UNC path. At that point, checking only Linux processes inside WSL may miss the process that actually tried to open the database. SQLite locking is straightforward on a local filesystem, but Windows/WSL boundary paths can change the failure mode.

In other words, database is locked does not always mean an active holder exists. If no holder appears, inspect the access path next.

Check whether the SQLite DB is actually damaged¶

Before deleting state files, run read-only checks from inside WSL.

ls -la ~/.codex-app
fuser ~/.codex-app/state_5.sqlite
df -T ~/.codex-app
sqlite3 ~/.codex-app/state_5.sqlite "PRAGMA integrity_check;"
ps -ef | rg "codex|app-server"

Use these signals as a first pass.

Check	Low DB-damage signal
`fuser`	No process is reported as holding the file
`PRAGMA integrity_check`	Returns `ok`
`df -T`	The file lives on WSL ext4 from the Linux side
`ps`	No WSL-side Codex/app-server process remains

If those checks pass, continuing to treat the file as corrupt is usually the wrong direction. Backing up, recreating, or switching the DB to WAL mode may not help if the Windows app keeps opening the same state through \\wsl.localhost.

The next question is whether Codex App is launching a Linux binary inside WSL or a Windows codex.exe through a WSL wrapper.

Likely failure mode: Windows codex.exe runs even in WSL mode¶

The expected WSL-mode behavior is that the shell, working directory, and executable all live on the WSL side. Issue #21147 reports a case where Codex Desktop is configured for WSL, but the Windows codex.exe app-server is launched through WSL and the runtime remains Windows/PowerShell-oriented².

In the observed failure pattern, no WSL process holds state_5.sqlite, while a Windows codex.exe appears briefly during launch. That means searching for a Linux lock holder is not enough. The real question becomes: which OS-side process opened the DB, and through which path representation?

Inspect desktop logs and process traces for these clues.

Binary relocation: was the expected Linux codex binary available?
Spawn target: did the app launch codex, or codex.exe?
DB path: do \\wsl.localhost\... and /mnt/c/... paths appear?
Config home: are Windows and WSL CODEX_HOME / ~/.codex locations diverging?

Issue #22759 reports split configuration behavior in a Windows Desktop + WSL setup, where the Windows UI and the running WSL app-server may not be reading the same effective home/config source³. That makes the visible setting less authoritative than the process that actually launched.

If you are on 26.609.4994.0, check the known issue first¶

If the installed app version is 26.609.4994.0, check the public issue tracker before spending more time on local DB repair.

Issue #27979 was opened on June 12, 2026 for Windows Codex App 26.609.4994.0 no longer opening after an update, and it was still open when checked on June 13, 2026¹. The report describes the app package itself as installed, but the desktop app failing to open and existing app work/history becoming inaccessible.

That does not prove every WSL-mode user has the same root cause. It does mean that the same build number, Windows, WSL mode, and SQLite initialization failure should be treated as a possible app regression rather than only a personal state-file problem.

Sanitize anything you share publicly. Do not post full C:\Users\<user> paths, /home/<user> paths, workspace names, auth files, conversation history, or a complete .codex archive. Issue #23848 also warns that full .codex contents may include auth data and conversation history⁴.

Fast workaround: disable WSL mode temporarily¶

If the priority is to get the desktop app usable again, temporarily move to a Windows-native configuration.

Issue #23848 covers a different SQLite migration checksum failure, but its recovery flow is useful for avoiding the WSL path boundary: disable GUI WSL mode, use PowerShell, and let Codex regenerate only the local SQLite state DBs⁴. The root cause may differ from database is locked, but the workaround avoids the UNC/9p-style path layer.

The first sequence is the config-only recovery described at the top of this article. Set runCodexInWindowsSubsystemForLinux = false and integratedTerminalShell = "powershell" first. If the app opens, leave the SQLite state DB alone.

Only continue with the extra state reset if the app still fails.

Move the active workspace root to a Windows path
Move state_5.sqlite* and logs_2.sqlite* aside
Restart Codex App so it can regenerate those local SQLite files

Move files aside instead of deleting them immediately. Also inspect any .codex or .codex-app directory before sharing or removing it, because it may include sensitive state.

If WSL mode is required, wait for a fix or roll back¶

For projects that depend on Linux tooling inside WSL, the Windows-native workaround is only a temporary escape hatch. The durable choices are to wait for a fixed build or, if your organization allows it, roll back to the last known working app version.

Avoid spending time on DB-only fixes when the launch path is wrong.

Switching SQLite to WAL: may help real concurrent writes, but not a bad Windows/WSL launch path
Recreating state_5.sqlite: can fail again if the app reopens it through the same path
Manually placing a Linux codex binary: may not help if the app decides from the packaged source file rather than the destination

A "locked" error with no visible holder is a path and process problem until proven otherwise. For Codex App in WSL mode, inspect version, spawned binary, DB path, and config home together.

Summary: inspect path and build before repairing the DB¶

Codex App's database is locked error looks like a SQLite corruption problem. But if the message includes \\wsl.localhost\..., WSL shows no holder, and the app version matches a known startup-failure build such as 26.609.4994.0, DB repair should not be the first response.

The order is database, process, path, then build number. That sequence protects authentication data and session history while making the recovery choice clearer: Windows-native fallback, rollback, or waiting for a fixed release.

The operational lesson is to share less local detail, not more. For useful incident reports, the build number, OS, WSL-mode setting, database path style, and spawned binary name matter more than personal paths or raw logs.