SONAManager: unsupported schemaVersion ${decoded.schemaVersi

Error message

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

What it means

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.

Source

Thrown at v3/@claude-flow/neural/src/sona-manager.ts:646

  deserialize(state: unknown): void {
    const decoded = deepDecode(state) as {
      schemaVersion: number;
      currentMode: SONAMode;
      config: SONAModeConfig;
      optimizations: ModeOptimizations;
      trajectories: Map<string, Trajectory>;
      patterns: Map<string, Pattern>;
      loraWeights: Map<string, LoRAWeights>;
      ewcState: EWCState | null;
      stats: NeuralStats;
      isInitialized: boolean;
      operationCount: number;
      totalLatencyMs: number;
      learningCycles: number;
      lastStatsUpdate: number;
    };
    if (decoded.schemaVersion !== 1) {
      throw new Error(`SONAManager: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)`);
    }
    this.currentMode = decoded.currentMode;
    this.config = decoded.config;
    this.optimizations = decoded.optimizations;
    this.modeImpl = this.createModeImplementation(this.currentMode);
    this.trajectories = decoded.trajectories;
    this.patterns = decoded.patterns;
    this.loraWeights = decoded.loraWeights;
    this.ewcState = decoded.ewcState;
    this.stats = decoded.stats;
    this.isInitialized = decoded.isInitialized;
    this.operationCount = decoded.operationCount;
    this.totalLatencyMs = decoded.totalLatencyMs;
    this.learningCycles = decoded.learningCycles;
    this.lastStatsUpdate = decoded.lastStatsUpdate;
  }

  // ==========================================================================

View on GitHub (pinned to fa13ee4ad6)

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

Example fix

// before
await manager.load(saved);
// after
const peek = JSON.parse(typeof saved === 'string' ? saved : saved.toString('utf8'));
if (peek.schemaVersion !== 1) {
  await rebuildStateFromTrajectories(); // discard incompatible snapshot
} else {
  await manager.load(saved);
}

Defensive patterns

Strategy: validation

Validate before calling

// peek at the envelope before restoring
const peek = JSON.parse(
  typeof saved === 'string' ? saved : saved.toString('utf8'),
);
if (peek?.schemaVersion !== 1) {
  await rebuildState(); // do not call load() with incompatible data
} else {
  await manager.load(saved);
}

Type guard

function isV1Snapshot(s: unknown): s is { schemaVersion: 1 } {
  return (
    typeof s === 'object' &&
    s !== null &&
    (s as Record<string, unknown>).schemaVersion === 1
  );
}

Try / catch

try {
  await manager.load(saved);
} catch (e) {
  if (String(e).includes('unsupported schemaVersion')) {
    await rebuildState(); // discard and retrain instead of crashing
  } else {
    throw e;
  }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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