hermes - 💡(How to fix) Fix SessionDB: no crash recovery path when state.db is corrupted after unclean shutdown

Official PRs (…)
ON THIS PAGE

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…

Error Message

When state.db is in an inconsistent state (e.g., after an unclean shutdown during a WAL write), SessionDB.__init__ catches the error and creates fresh empty tables, discarding all session history without any recovery attempt. On corrupted/unreadable state.db, attempt to recover from session JSON files in sessions/. If recovery succeeds, rebuild messages and messages_fts from JSON. If recovery fails, log the error and rebuild empty tables (current behavior).

Root Cause

SessionDB.__init__ in hermes_state.py calls _init_schema() on startup. If the database file is corrupted or in an inconsistent state, the connection fails and _init_schema() rebuilds the schema from scratch — creating empty messages, sessions, and messages_fts tables.

There is no logic to:

  1. Detect that the database was previously populated
  2. Fall back to session JSON files in ~/.hermes/sessions/ for recovery
  3. Preserve existing data before schema reconciliation
RAW_BUFFERClick to expand / collapse

SessionDB: no crash recovery path when state.db is corrupted

Bug Description

When state.db is in an inconsistent state (e.g., after an unclean shutdown during a WAL write), SessionDB.__init__ catches the error and creates fresh empty tables, discarding all session history without any recovery attempt.

Root Cause

SessionDB.__init__ in hermes_state.py calls _init_schema() on startup. If the database file is corrupted or in an inconsistent state, the connection fails and _init_schema() rebuilds the schema from scratch — creating empty messages, sessions, and messages_fts tables.

There is no logic to:

  1. Detect that the database was previously populated
  2. Fall back to session JSON files in ~/.hermes/sessions/ for recovery
  3. Preserve existing data before schema reconciliation

Expected Behavior

On corrupted/unreadable state.db, attempt to recover from session JSON files in sessions/. If recovery succeeds, rebuild messages and messages_fts from JSON. If recovery fails, log the error and rebuild empty tables (current behavior).

Environment

  • Hermes v0.14.0
  • SQLite WAL journal mode
  • Session storage: ~/.hermes/state.db + ~/.hermes/sessions/session_*.json

Reproduction Steps

  1. Run Hermes gateway for an extended session (2+ hours)
  2. Force an unclean shutdown (OOM kill, kill -9, power loss)
  3. Observe that state.db is rebuilt with empty tables on next startup
  4. Session JSON files in sessions/ survive the crash but are not used for recovery

Possible Solution

On SessionDB.__init__ failure, scan ~/.hermes/sessions/*.json. For each JSON file not represented in the sessions table, insert messages into messages. This makes JSON files the authoritative backup of session history.

Files Likely Involved

  • hermes_agent/hermes_state.pySessionDB.__init__, _init_schema(), session persistence logic

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…

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

hermes - 💡(How to fix) Fix SessionDB: no crash recovery path when state.db is corrupted after unclean shutdown