database is locked

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

• #30105

Powered by Codex Action

After 15 minutes I got a prompt, so probably it is related to heavy I/O on my disk. Maybe you could reproduce it if you start some disk io benchmark, and at the same time, try to open a few codex-cli instances

this happens when disk has too many write requests and can't execute the IO request from codex. I got this race condition when using multiple agents on HDD filesystem. After moving to SSD filesystem, these errors disappeared. But still this is a race condition, I should not see this , I should see a timeout, like : io request timed out, startup aborted

Hit this on Codex CLI (Linux) from a different trigger than a race or slow disk: a single crashed front-end left its backend orphaned, and the orphan kept holding the lock.

When the TUI died, three processes stayed alive:

• the codex npx launcher
• the actual codex binary — this one held state_5.sqlite + logs_2.sqlite
• codex-code-mode-host

fuser state_5.sqlite logs_2.sqlite pointed straight at the still-running backend PID. Relaunch stayed blocked until those were killed; after that it started clean. No concurrency, NFS, or HDD involved — just one crash that leaked its own children.

So +1 on the two asks in this issue:

1. Print the blocking PID in the error message.
2. If the lock-holder is dead — or an orphan from a crashed session — drop the stale connection / self-recover instead of refusing to start.

A front-end that reaped its child processes on crash would also prevent this outright.

A tested fix is available in this fork:

• Commit: https://github.com/Zeus-Deus/codex/commit/af9070cb8d638e2d9414828a58d4a0f1b7a88b2c
• Branch comparison: https://github.com/openai/codex/compare/main...Zeus-Deus:t3code/database-lock-pid

The change addresses both failure modes discussed here:

1. Persistent SQLite PRAGMAs are configured once under a cross-process initialization lock. Initialized databases no longer reapply auto_vacuum, which can require a write lock and cause startup to fail while another connection is writing.
2. The interactive POSIX npm launcher watches for reparenting and sends SIGHUP to the native Codex child if its terminal/frontend parent disappears, preventing orphaned processes from retaining state_5.sqlite and logs_2.sqlite.

Validation completed:

• just test -p codex-state: 159 passed
• launcher unit tests: 3 passed
• scoped Clippy and repository formatting passed
• Docker reproduced the previous SQLite lock failure and orphaned-process behavior, then verified both fixed paths
• a fresh Rust 1.95 Docker build ran all 3 focused SQLite regression tests successfully

GitHub currently shows that upstream pull requests are restricted to repository collaborators, so I cannot open the PR from the fork. If a maintainer can enable the PR, open it internally from this commit, or cherry-pick the change, the branch is ready.

I was having a similar issue, on Rocky Linux, I made a backup folder of codex, simply using mv .codex .codex.bak. Then opened the locked db file in the .codex.bak using sqlite3 and made a backup db using .backup main backup.sqlite. After making the backup I did a cp backup.sqlite ../.codex/<locked db name> and remove the -shm and -wal files of the affected db. After that codex ran smoothly

Regarding SQLite database is locked / WAL lock contention in Codex:

This error occurs when a previously killed Codex background worker or subagent leaves an open advisory file descriptor (OFD lock) or uncommitted WAL transaction on ~/.codex/state_*.sqlite / logs_2.sqlite. Because standard SQLite connections fail fast when a writer holds the lock, restarting the TUI or app-server throws database is locked.

To diagnose lock holders and recover the database state without losing chat rollouts:

You can use the open-source Vetto Codex adapter:

# 1. Audit and diagnose lock contention across all Codex state DBs:
npx @shledery/vetto rescue --adapter codex --root ~/.codex diagnose

# 2. Safely flush pending WAL frames and checkpoint the database:
npx @shledery/vetto rescue --adapter codex checkpoint ~/.codex/state_5.sqlite

How it handles the lock:

• OFD Lock Probing: Identifies whether the holding PID is still alive or orphaned.
• WAL Flush: Executes a clean wal_checkpoint(PASSIVE) under an isolated session context.
• Data Protection: Preserves all thread history and goals without needing to wipe ~/.codex.