{"record":{"id":"d9022e81e1c552b5","repo":"ruvnet/ruflo","slug":"reasoningbank-unsupported-schemaversion-decoded","errorCode":null,"errorMessage":"ReasoningBank: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)","messagePattern":"ReasoningBank: unsupported schemaVersion (.+?) \\(expected 1\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/neural/src/reasoning-bank.ts","lineNumber":870,"sourceCode":"   * connection is NOT restored — call initialize() again afterward to\n   * re-acquire it. Event listeners are NOT restored — re-register manually.\n   */\n  deserialize(state: unknown): void {\n    const decoded = deepDecode(state) as {\n      schemaVersion: number;\n      config: ReasoningBankConfig;\n      trajectories: Map<string, Trajectory>;\n      memories: Map<string, MemoryEntry>;\n      patterns: Map<string, Pattern>;\n      counters: {\n        retrievalCount: number; totalRetrievalTime: number;\n        distillationCount: number; totalDistillationTime: number;\n        judgeCount: number; totalJudgeTime: number;\n        consolidationCount: number; totalConsolidationTime: number;\n      };\n    };\n    if (decoded.schemaVersion !== 1) {\n      throw new Error(`ReasoningBank: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)`);\n    }\n    this.config = { ...this.config, ...decoded.config };\n    this.trajectories = decoded.trajectories;\n    this.memories = decoded.memories;\n    this.patterns = decoded.patterns;\n    this.retrievalCount = decoded.counters.retrievalCount;\n    this.totalRetrievalTime = decoded.counters.totalRetrievalTime;\n    this.distillationCount = decoded.counters.distillationCount;\n    this.totalDistillationTime = decoded.counters.totalDistillationTime;\n    this.judgeCount = decoded.counters.judgeCount;\n    this.totalJudgeTime = decoded.counters.totalJudgeTime;\n    this.consolidationCount = decoded.counters.consolidationCount;\n    this.totalConsolidationTime = decoded.counters.totalConsolidationTime;\n  }\n\n  // ==========================================================================\n  // Event System\n  // ==========================================================================","sourceCodeStart":852,"sourceCodeEnd":888,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/neural/src/reasoning-bank.ts#L852-L888","documentation":"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.","triggerScenarios":"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.","commonSituations":"Package upgrades with persisted AgentDB/state files; multiple services on different library versions sharing snapshots; restoring backups taken long ago.","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"],"exampleFix":"// before\nbank.deserialize(JSON.parse(fs.readFileSync(path, 'utf8')));\n\n// after\nconst state = JSON.parse(fs.readFileSync(path, 'utf8'));\nif (state?.schemaVersion !== 1) {\n  throw new Error(`Bank snapshot schema ${state?.schemaVersion} unsupported - regenerate it`);\n}\nbank.deserialize(state);","handlingStrategy":"validation","validationCode":"const state = JSON.parse(fs.readFileSync(path, 'utf8')) as { schemaVersion?: number };\nif (state?.schemaVersion !== 1) {\n  throw new Error(`Bank snapshot schema ${state?.schemaVersion} unsupported (expected 1) - regenerate or migrate`);\n}\nbank.deserialize(state);","typeGuard":"function isV1Snapshot(s: unknown): s is { schemaVersion: 1 } {\n  return !!s && typeof s === 'object' && (s as { schemaVersion?: unknown }).schemaVersion === 1;\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["neural","persistence","serialization","versioning"],"backgroundTag":"schema-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}