Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Bug]: ocx doctor reports a false history integrity failure when state_5.sqlite is WAL without -shm

Closed Beginner friendly
  • Is something wrong?
#7,044 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
sqlite, typescript
Domain
cli, database

Research direction

Start with countPendingOpencodexHistory in src/codex/history-provider.ts and compare its database opening with openCodexStateForPreflight in src/codex/history-state-open.ts, which handles WAL databases without -shm. Check the existing tests for these paths, then add coverage for a WAL state database without -shm; done means ocx doctor no longer reports a false integrity failure for that case.

Written by the indexing model from the issue text.

Description

bug cli
Client or integration

Codex CLI

Area

CLI

Summary

ocx doctor reports "backup manifest or restore target failed integrity checks — manual review required" when Codex's state_5.sqlite is a WAL database with no live writer (no -wal/-shm files). countPendingOpencodexHistory (src/codex/history-provider.ts:1834) opens the DB with new Database(path, { readonly: true }); SQLite cannot open a WAL database read-only without -shm (SQLITE_CANTOPEN). The error is not classified as recoverable and falls through to failureReason: "integrity".

openCodexStateForPreflight (src/codex/history-state-open.ts:86) already handles exactly this case with an ?immutable=1 fallback (from #4943), but countPendingOpencodexHistory does not use it.

Reproduction
  1. Quit all Codex processes so ~/.codex/state_5.sqlite-wal and -shm are gone.
  2. sqlite3 "file:$HOME/.codex/state_5.sqlite?mode=ro" "SELECT 1 FROM threads LIMIT 1" → unable to open database file (14).
  3. ocx doctor → integrity warning under "Codex native-write coordinator".

On a machine where Codex is running (WAL files present) the same check prints ok.

Version

@bitkyc08/opencodex 2.84.0, codex-cli 0.162.1

Operating system

macOS 27 (Apple Silicon)

Provider and model

n/a

Logs or error output
Codex native-write coordinator
  --     backup manifest or restore target failed integrity checks — manual review required
Redacted configuration

Client mode, no history backup entries pending.

Proposed fix

Open the state DB in countPendingOpencodexHistory via openCodexStateForPreflight(stateDbPath) (or classify SQLITE_CANTOPEN without WAL files as "busy"/unknown instead of "integrity").

Related: #4943.

Screenshots and supporting files

No response

Checks
  • I searched existing issues and documentation.
  • I removed secrets, tokens, account details, request credentials, and personal data.
Dominant language
TypeScript
Stars
16.9k
Forks
1.3k
Avg merge
7h 50m
Merged PRs (30d)
645

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lidge-jun/opencodex

All issues in lidge-jun/opencodex

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.