Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Bug]: SQLite WAL files in ~/.openclaw grow unbounded; gateway-held reader blocks autocheckpoint truncation [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#72774•Fetched 2026-04-28 06:32:22
View on GitHub
Comments
1
Participants
2
Timeline
4
Reactions
1
Author
dfpalhanodfpalhano
Participants
dfpalhanodfpalhanosteipetesteipete
Timeline (top)
closed ×1commented ×1mentioned ×1subscribed ×1

On a long-running gateway, the WAL files for ~/.openclaw/tasks/runs.sqlite and ~/.openclaw/flows/registry.sqlite grow without bound and never truncate while the gateway is up. After the WAL had been observed at multi-MB sizes, a single PRAGMA wal_checkpoint(TRUNCATE); from sqlite3 instantly flushed both to zero.

Root Cause

On a long-running gateway, the WAL files for ~/.openclaw/tasks/runs.sqlite and ~/.openclaw/flows/registry.sqlite grow without bound and never truncate while the gateway is up. After the WAL had been observed at multi-MB sizes, a single PRAGMA wal_checkpoint(TRUNCATE); from sqlite3 instantly flushed both to zero.

Code Example

-rw-------. 1 user user  4161232 Apr 27 17:48 ~/.openclaw/tasks/runs.sqlite-wal     # 4.1 MB
-rw-------. 1 user user   939392 Apr 23 15:29 ~/.openclaw/flows/registry.sqlite-wal # 939 KB
RAW_BUFFERClick to expand / collapse

Summary

On a long-running gateway, the WAL files for ~/.openclaw/tasks/runs.sqlite and ~/.openclaw/flows/registry.sqlite grow without bound and never truncate while the gateway is up. After the WAL had been observed at multi-MB sizes, a single PRAGMA wal_checkpoint(TRUNCATE); from sqlite3 instantly flushed both to zero.

Environment

  • OpenClaw 2026.4.24
  • Linux 6.12.0 (Rocky Linux 10.1)
  • Node v25.8.0
  • Gateway running as systemd-user service for ~13h
  • journal_mode = WAL (set in src/tasks/task-registry.store.sqlite.ts:450 and src/tasks/task-flow-registry.store.sqlite.ts:344)

Observed

-rw-------. 1 user user  4161232 Apr 27 17:48 ~/.openclaw/tasks/runs.sqlite-wal     # 4.1 MB
-rw-------. 1 user user   939392 Apr 23 15:29 ~/.openclaw/flows/registry.sqlite-wal # 939 KB

After PRAGMA wal_checkpoint(TRUNCATE); returns 0|0|0, both WAL files are removed and the main DB picks up the deltas. The gateway continues without restart.

Suspected cause

The gateway opens a long-lived DatabaseSync connection (via node:sqlite). Default wal_autocheckpoint (1000 frames) checks at COMMIT time, but a persistent reader/writer can keep the WAL "in use" so SQLite is unable to truncate the WAL file even after it copies pages back to the main DB; it can only PASSIVE-checkpoint and reuse the file. Without an explicit wal_checkpoint(TRUNCATE) step, the file size stays at the high-water mark.

Impact

  • Slow disk-space leak on operator hosts (Diego's host: ~5 MB across two DBs after a few days, but unbounded for high-write workloads).
  • Power-loss recovery rolls back fewer pages than the operator expects: the WAL is large, so post-crash recovery has more work; also any unflushed WAL pages are lost on power loss vs. having been checkpointed into the main DB.
  • Backups that snapshot only *.sqlite (not -wal) silently capture stale state.

Expected

  • Periodic wal_checkpoint(TRUNCATE) on gateway shutdown and on a timer (e.g., hourly) to keep WAL files bounded.
  • Or set PRAGMA wal_autocheckpoint = N to a lower value paired with a periodic TRUNCATE invocation.

Proposed fix

At each task-registry.store.sqlite.ts / task-flow-registry.store.sqlite.ts open path, after PRAGMA journal_mode = WAL;:

  1. Add PRAGMA wal_autocheckpoint = 1000; explicitly (current default).
  2. Schedule a low-priority periodic db.exec("PRAGMA wal_checkpoint(TRUNCATE);") (e.g., every 30 min) to bound disk usage.
  3. Run wal_checkpoint(TRUNCATE) on graceful shutdown of the gateway.

Same fix applies to ~/.openclaw/lcm.db (memory plugin DB).

Repro

  1. Run gateway as long-lived service with task/flow activity for 24h+.
  2. ls -l ~/.openclaw/tasks/runs.sqlite-wal — should reach multi-MB and not shrink.
  3. From outside the gateway: sqlite3 ~/.openclaw/tasks/runs.sqlite "PRAGMA wal_checkpoint(TRUNCATE);" — WAL drops to 0 bytes immediately.

Reported by @dfpalhano during reliability audit.

extent analysis

TL;DR

Implement a periodic wal_checkpoint(TRUNCATE) to prevent unbounded growth of WAL files for SQLite databases in the OpenClaw gateway.

Guidance

  • To mitigate the issue, consider setting PRAGMA wal_autocheckpoint to a lower value and pair it with a periodic TRUNCATE invocation.
  • Schedule a low-priority periodic db.exec("PRAGMA wal_checkpoint(TRUNCATE);") (e.g., every 30 minutes) to bound disk usage.
  • Run wal_checkpoint(TRUNCATE) on graceful shutdown of the gateway to ensure WAL files are truncated.
  • Verify the fix by monitoring the size of WAL files over time and checking that they are being truncated as expected.

Example

db.exec("PRAGMA wal_autocheckpoint = 1000;");
// Schedule a periodic checkpoint
setInterval(() => {
  db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
}, 30 * 60 * 1000); // every 30 minutes

Notes

The proposed fix applies to all SQLite databases used by the OpenClaw gateway, including ~/.openclaw/lcm.db. The frequency of the periodic checkpoint may need to be adjusted based on the specific workload and performance requirements.

Recommendation

Apply the proposed fix by implementing a periodic wal_checkpoint(TRUNCATE) to prevent unbounded growth of WAL files. This will help prevent slow disk-space leaks, ensure power-loss recovery rolls back the expected number of pages, and capture accurate state in backups.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#model save/load#optimization#mixed precision#training loop#device allocation

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix [Bug]: SQLite WAL files in ~/.openclaw grow unbounded; gateway-held reader blocks autocheckpoint truncation [1 comments, 2 participants]