openclaw - 💡(How to fix) Fix [Bug] sessions.json can become 0 bytes (empty), breaking session aggregation with no recovery mechanism [1 comments, 2 participants]

Bug Description

sessions.json can become corrupted (0 bytes), causing silent session aggregation failures. When this happens, OpenClaw cannot list or manage sessions properly, and there's no automatic recovery mechanism.

Environment

• OpenClaw version: 2026.5.3-1
• OS: Linux 6.8.0-110-generic (x64)
• Node: v22.22.2
• Gateway: systemd user service
• Session store: ~/.openclaw/agents/main/sessions/sessions.json

Observed State

$ ls -la ~/.openclaw/state/sessions.json
-rw-rw-r-- 1 moltbot moltbot 0 May 5 16:58 sessions.json

$ wc -c ~/.openclaw/state/sessions.json
0 /home/moltbot/.openclaw/state/sessions.json

Session directory: 7,806 jsonl files (404MB total)

Symptoms

1. Session operations fail silently

   • sessions.list may timeout or return empty
   • Session aggregation cannot complete
   • No user-facing error message

2. SessionWriteLockTimeoutError cascades

   • Lock held for 60s (timeout)
   • Event loop starvation (ELD P99=7,772ms)
   • Discord slash commands fail ("Application did not respond")

3. No automatic recovery

   • File remains 0 bytes indefinitely
   • Manual intervention required: echo "[]" > sessions.json

Root Cause Hypothesis

Likely caused by:

• Concurrent write during session compaction
• Gateway restart mid-write
• Session file lock contention during heavy load

Impact

• Complete session management failure - Cannot list, archive, or prune sessions
• Cascading failures - Event loop starvation affects all channels
• Data loss risk - If sessions.json is the source of truth for active sessions

Expected Behavior

1. Atomic writes - Use temp file + rename pattern for sessions.json updates
2. Corruption detection - Validate JSON on read, trigger rebuild if invalid
3. Automatic recovery - If sessions.json is empty/invalid, rebuild from session directory scan
4. Health check - openclaw doctor should flag empty/corrupted sessions.json

Reproduction Steps

1. Have high session file count (~7,000+ files)
2. Trigger session compaction or heavy concurrent operations
3. Force gateway restart during active session write (SIGTERM)
4. Check ~/.openclaw/state/sessions.json - may be 0 bytes

Workaround

# Manual recovery
echo "[]" > ~/.openclaw/state/sessions.json

# Then restart gateway
systemctl --user restart openclaw-gateway

Related Issues

• #75839 - pi-trajectory-flush timeout with high session count
• #13744 - Make session write lock configurable
• #77716 - Discord AbortError during event loop saturation
• #76421 - sessions.list timeout after event loop stall

Suggested Fix

1. Write atomicity:

// Pseudo-code for atomic session.json update
const tmpFile = `${sessionFile}.tmp.${Date.now()}`;
fs.writeFileSync(tmpFile, JSON.stringify(sessions));
fs.renameSync(tmpFile, sessionFile); // Atomic on POSIX

1. Validation on read:

const data = fs.readFileSync(sessionFile, 'utf8');
if (!data || data.length === 0) {
  logger.warn('sessions.json is empty, rebuilding...');
  return rebuildFromSessionDir();
}

1. Rebuild function:

function rebuildFromSessionDir() {
  const sessionFiles = fs.readdirSync(sessionsDir)
    .filter(f => f.endsWith('.jsonl'))
    .map(f => parseSessionFile(f));
  return sessionFiles;
}

1. Health check: Add to openclaw doctor:

[FAIL] sessions.json is 0 bytes (corrupted)
  Fix: Run `openclaw sessions rebuild-index`

Evidence from 2026-05-05 Incident

• sessions.json: 0 bytes (corrupted)
• Session files: 7,806 jsonl files
• SessionWriteLockTimeoutError at 17:35:58 and 18:23:26
• Event loop utilization: 95.8%
• Discord slash commands: "Application did not respond"
• Fixed by: echo "[]" > sessions.json + gateway restart