{"record":{"id":"017c3b866d11264a","repo":"ruvnet/ruflo","slug":"sonamanager-unsupported-schemaversion-decoded-s","errorCode":null,"errorMessage":"SONAManager: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)","messagePattern":"SONAManager: unsupported schemaVersion (.+?) \\(expected 1\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/neural/src/sona-manager.ts","lineNumber":646,"sourceCode":"  deserialize(state: unknown): void {\n    const decoded = deepDecode(state) as {\n      schemaVersion: number;\n      currentMode: SONAMode;\n      config: SONAModeConfig;\n      optimizations: ModeOptimizations;\n      trajectories: Map<string, Trajectory>;\n      patterns: Map<string, Pattern>;\n      loraWeights: Map<string, LoRAWeights>;\n      ewcState: EWCState | null;\n      stats: NeuralStats;\n      isInitialized: boolean;\n      operationCount: number;\n      totalLatencyMs: number;\n      learningCycles: number;\n      lastStatsUpdate: number;\n    };\n    if (decoded.schemaVersion !== 1) {\n      throw new Error(`SONAManager: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)`);\n    }\n    this.currentMode = decoded.currentMode;\n    this.config = decoded.config;\n    this.optimizations = decoded.optimizations;\n    this.modeImpl = this.createModeImplementation(this.currentMode);\n    this.trajectories = decoded.trajectories;\n    this.patterns = decoded.patterns;\n    this.loraWeights = decoded.loraWeights;\n    this.ewcState = decoded.ewcState;\n    this.stats = decoded.stats;\n    this.isInitialized = decoded.isInitialized;\n    this.operationCount = decoded.operationCount;\n    this.totalLatencyMs = decoded.totalLatencyMs;\n    this.learningCycles = decoded.learningCycles;\n    this.lastStatsUpdate = decoded.lastStatsUpdate;\n  }\n\n  // ==========================================================================","sourceCodeStart":628,"sourceCodeEnd":664,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/neural/src/sona-manager.ts#L628-L664","documentation":"SONAManager round-trips its state through a versioned snapshot envelope; on restore the decoder requires decoded.schemaVersion to be exactly 1 before assigning any field. Any other value (0, 2, undefined, a string) aborts deserialization immediately, leaving the manager's existing state untouched. This is a deliberate fail-fast guard against restoring incompatible persistence formats.","triggerScenarios":"Loading a snapshot produced by a different release whose format changed (schemaVersion 2), a snapshot whose envelope was hand-edited or truncated so schemaVersion parses to a wrong type, or a buffer that was decoded through the wrong pathway producing garbage.","commonSituations":"Upgrading or downgrading @claude-flow/neural across a persistence-format change; snapshot files copied between environments running mixed versions; state files written by an external tool or script.","solutions":["Confirm which package version wrote the snapshot (its format version) and pin all nodes to a matching version","If the snapshot is from an incompatible version, discard it and rebuild SONA state by re-running learning cycles","If you control the writer, migrate the envelope: read it, rewrite schemaVersion and any changed fields, re-save","Never hand-edit persisted snapshots; treat them as opaque output of the exact manager version"],"exampleFix":"// before\nawait manager.load(saved);\n// after\nconst peek = JSON.parse(typeof saved === 'string' ? saved : saved.toString('utf8'));\nif (peek.schemaVersion !== 1) {\n  await rebuildStateFromTrajectories(); // discard incompatible snapshot\n} else {\n  await manager.load(saved);\n}","handlingStrategy":"validation","validationCode":"// peek at the envelope before restoring\nconst peek = JSON.parse(\n  typeof saved === 'string' ? saved : saved.toString('utf8'),\n);\nif (peek?.schemaVersion !== 1) {\n  await rebuildState(); // do not call load() with incompatible data\n} else {\n  await manager.load(saved);\n}","typeGuard":"function isV1Snapshot(s: unknown): s is { schemaVersion: 1 } {\n  return (\n    typeof s === 'object' &&\n    s !== null &&\n    (s as Record<string, unknown>).schemaVersion === 1\n  );\n}","tryCatchPattern":"try {\n  await manager.load(saved);\n} catch (e) {\n  if (String(e).includes('unsupported schemaVersion')) {\n    await rebuildState(); // discard and retrain instead of crashing\n  } else {\n    throw e;\n  }\n}","preventionTips":["Tag snapshot files with the package version that wrote them","Pin all environments to one @claude-flow/neural version","Never hand-edit persisted snapshots","On upgrade, test load() against old snapshots before deploying"],"tags":["persistence","versioning","deserialization"],"backgroundTag":"schema-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}