// OPENBOX DOCS

Troubleshooting state recovery

Diagnose corrupt library state and recover from the backup copy.

OpenBoxGL writes library state atomically with a last-known-good backup, so a crash or bad edit cannot silently corrupt the library. When corruption does happen, recovery is explicit and safe.

How to read the state

  • The library is library.json (schema version 7) with a .bak last-known-good copy, a .lock file, and sessions.json for active sessions beside it. Writes are atomic and owner-only.
  • Stable game IDs (game-<hex>) survive reordering; legacy index-suffixed IDs are kept as aliases (legacy_game_ids).

When recovery is needed

If the primary file cannot be read, API operations return 503 with:

{"error":"OpenBox library data needs recovery before this operation can continue."}

The original file is preserved, never overwritten.

Recover

Recovery (POST /api/v2/state/recover) can inspect available backups or restore either the .bak file or a rolling snapshot:

Dry-run inspection

Send POST /api/v2/state/recover with {"dry_run": true} to inspect recovery options without modifying state:

{
  "dry_run": true,
  "backup_available": true,
  "games": 42,
  "snapshots": [
    {
      "name": "20260823T153000123456Z-00000007-a1b2c3d4.json",
      "modified": 1723896000.0,
      "size": 154200
    }
  ]
}

Snapshot names embed the UTC timestamp to microseconds, a sequence number, and a random suffix (<timestamp>-<sequence>-<hex>.json). Listing is newest-first by that embedded timestamp and sequence, not by file mtime, so two snapshots written in the same clock tick still sort correctly. A hand-placed filename without that format falls back to mtime ordering.

Restoring state

  • Restore last-known-good backup: POST /api/v2/state/recover with {} loads library.json.bak, validates/normalizes it, and commits it atomically.
  • Restore specific snapshot: POST /api/v2/state/recover with {"snapshot": "20260823T153000123456Z-00000007-a1b2c3d4.json"} restores a point-in-time snapshot from library.json.snapshots/ (retains the 5 most recent rolling snapshots).

Success returns {"ok": true, "games": <count>}.

MessageMeaning
"No last-known-good state exists at <bak path>."No .bak exists; there is nothing to recover from.
"The last-known-good state is also unusable: <bak path>"Both primary and backup are bad; recovery fails clearly rather than guessing.
"Unknown snapshot: <name>"Specified snapshot filename does not exist in library.json.snapshots/.

Upgrading to 3.0

3.0 does not migrate a library on open. Schema 7 opens directly. A schema 6 library raises STATE_SCHEMA_TOO_OLD and is left unchanged until you run openbox --migrate-library; the command writes library.v6.backup.json, migration-in-progress.json, and migration-report.json. A schema 1-5 library must be opened once on OpenBox 2.1 first. After a migration, the readiness gate lists anything that needs a look — a theme with unknown tokens, a plugin API version this build does not serve, a missing sync folder, an archive with no format, a library over the formal scale, or a custom data directory.

openbox --rollback-library was removed in 3.0: it exits 4 and changes no file. OpenBox 2.1.0 is the last build that restores library.v6.backup.json. 3.0 does not delete an existing v6 backup.

Preventing data loss

  • Back up the whole data directory before manual intervention: copy library.json and library.json.bak together.
  • Rolling snapshots are automatically saved in library.json.snapshots/ before schema migrations or major updates (capped at 5 rotating snapshots).
  • A schema above 7 raises STATE_FUTURE_VERSION and is never rewritten. A schema below 7 raises STATE_SCHEMA_TOO_OLD on open; use openbox --migrate-library for schema 6, and OpenBox 2.1 for schema 1-5.
  • The .bak is always at least as fresh as the primary commit that preceded the last write, because it is written before the swap.

See also