ReasoningBank: unsupported schemaVersion ${decoded.schemaVer

Error message

ReasoningBank: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)

What it means

ReasoningBank.serialize() stamps snapshots with schemaVersion 1; deserialize() throws when the state carries any other schemaVersion, before touching the stored trajectories/memories/patterns. This is a compatibility guard across releases: deserialization replaces all bank state in one shot, so an unrecognized layout must abort before partial import.

Source

Thrown at v3/@claude-flow/neural/src/reasoning-bank.ts:870

   * connection is NOT restored — call initialize() again afterward to
   * re-acquire it. Event listeners are NOT restored — re-register manually.
   */
  deserialize(state: unknown): void {
    const decoded = deepDecode(state) as {
      schemaVersion: number;
      config: ReasoningBankConfig;
      trajectories: Map<string, Trajectory>;
      memories: Map<string, MemoryEntry>;
      patterns: Map<string, Pattern>;
      counters: {
        retrievalCount: number; totalRetrievalTime: number;
        distillationCount: number; totalDistillationTime: number;
        judgeCount: number; totalJudgeTime: number;
        consolidationCount: number; totalConsolidationTime: number;
      };
    };
    if (decoded.schemaVersion !== 1) {
      throw new Error(`ReasoningBank: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)`);
    }
    this.config = { ...this.config, ...decoded.config };
    this.trajectories = decoded.trajectories;
    this.memories = decoded.memories;
    this.patterns = decoded.patterns;
    this.retrievalCount = decoded.counters.retrievalCount;
    this.totalRetrievalTime = decoded.counters.totalRetrievalTime;
    this.distillationCount = decoded.counters.distillationCount;
    this.totalDistillationTime = decoded.counters.totalDistillationTime;
    this.judgeCount = decoded.counters.judgeCount;
    this.totalJudgeTime = decoded.counters.totalJudgeTime;
    this.consolidationCount = decoded.counters.consolidationCount;
    this.totalConsolidationTime = decoded.counters.totalConsolidationTime;
  }

  // ==========================================================================
  // Event System
  // ==========================================================================

View on GitHub (pinned to fa13ee4ad6)

Solutions

Regenerate the snapshot with the current version (serialize() after a clean run)
Downgrade to the version that wrote the file, load and re-export the state, then upgrade
Check state.schemaVersion === 1 before calling deserialize() and branch to a migration path

Example fix

// before
bank.deserialize(JSON.parse(fs.readFileSync(path, 'utf8')));

// after
const state = JSON.parse(fs.readFileSync(path, 'utf8'));
if (state?.schemaVersion !== 1) {
  throw new Error(`Bank snapshot schema ${state?.schemaVersion} unsupported - regenerate it`);
}
bank.deserialize(state);

Defensive patterns

Strategy: validation

Validate before calling

const state = JSON.parse(fs.readFileSync(path, 'utf8')) as { schemaVersion?: number };
if (state?.schemaVersion !== 1) {
  throw new Error(`Bank snapshot schema ${state?.schemaVersion} unsupported (expected 1) - regenerate or migrate`);
}
bank.deserialize(state);

Type guard

function isV1Snapshot(s: unknown): s is { schemaVersion: 1 } {
  return !!s && typeof s === 'object' && (s as { schemaVersion?: unknown }).schemaVersion === 1;
}

Prevention

Verify schemaVersion before deserialize() and migrate mismatches explicitly
Keep the writing and reading services on the same library version
Regenerate backups after upgrades instead of restoring old state files

When it happens

Trigger: Restoring a bank snapshot written by a different @claude-flow/neural version whose serialize() format changed; hand-edited or truncated JSON; loading a PatternLearner/SONAManager snapshot into the bank by mistake.

Common situations: Package upgrades with persisted AgentDB/state files; multiple services on different library versions sharing snapshots; restoring backups taken long ago.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/d9022e81e1c552b5. Report an issue: GitHub.