Unsupported uncertainty ledger version: ${data.version} (exp

Error message

Unsupported uncertainty ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})

What it means

Thrown by UncertaintyLedger.importBeliefs(data) when the serialized payload's version differs from the module's SERIALIZATION_VERSION. The import replaces all current beliefs wholesale (beliefs.clear() then re-populate), so a version gate prevents a foreign-format payload from corrupting the ledger. It fires before any mutation happens, leaving the ledger untouched.

Source

Thrown at v3/@claude-flow/guidance/src/uncertainty.ts:570

   * @returns Serialized ledger data suitable for JSON.stringify
   */
  exportBeliefs(): SerializedUncertaintyLedger {
    return {
      beliefs: Array.from(this.beliefs.values()).map(b => ({ ...b })),
      createdAt: new Date().toISOString(),
      version: SERIALIZATION_VERSION,
    };
  }

  /**
   * Import previously exported beliefs, replacing all current contents.
   *
   * @param data - Serialized ledger data
   * @throws If the version is unsupported
   */
  importBeliefs(data: SerializedUncertaintyLedger): void {
    if (data.version !== SERIALIZATION_VERSION) {
      throw new Error(
        `Unsupported uncertainty ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})`,
      );
    }
    this.beliefs.clear();
    for (const belief of data.beliefs) {
      this.beliefs.set(belief.id, { ...belief });
    }
  }

  /**
   * Get the number of tracked beliefs.
   */
  get size(): number {
    return this.beliefs.size;
  }

  /**
   * Get the current configuration.

View on GitHub (pinned to fa13ee4ad6)

Solutions

Re-export the ledger from an instance running the same guidance package version as the importer
Align @claude-flow/guidance versions across all producers and consumers (lockfile pinning)
Add a migration step that upgrades old payload versions to the current one before calling importBeliefs

Example fix

// before
ledger.importBeliefs(JSON.parse(backupJson)); // stale export -> throws

// after
const data = JSON.parse(backupJson);
if (data.version !== EXPECTED_VERSION) {
  throw new Error(`ledger backup is v${data.version}; regenerate on current version`);
}
ledger.importBeliefs(data);

Defensive patterns

Strategy: validation

Validate before calling

const data = JSON.parse(raw) as SerializedUncertaintyLedger & { version: number };
if (data.version !== importerVersion) {
  throw new Error(`ledger v${data.version} incompatible; re-export on v${importerVersion}`);
}
ledger.importBeliefs(data);

Type guard

function isCompatibleLedger(v: number): (d: unknown) => d is SerializedUncertaintyLedger {
  return (d): d is SerializedUncertaintyLedger =>
    typeof d === 'object' && d !== null && (d as { version?: unknown }).version === v;
}

Try / catch

try {
  ledger.importBeliefs(data);
} catch (e) {
  if (e instanceof Error && e.message.includes('Unsupported uncertainty ledger version')) {
    // beliefs map untouched — safe to migrate payload and retry
    ledger.importBeliefs(migrateBeliefs(data));
    return;
  }
  throw e;
}

Prevention

Record the producer version inside every persisted ledger export
Lock dependency versions in all services that share belief exports
Test import paths against fixtures from the current version in CI

When it happens

Trigger: Feeding a SerializedUncertaintyLedger produced by a different build of @claude-flow/guidance into importBeliefs — restoring a persisted ledger after a version upgrade, or receiving an export from another service/node running a different release.

Common situations: Rolling deployments with mixed package versions exchanging belief exports; long-lived snapshots loaded after dependency upgrades; copy-pasting fixtures between repos pinned to different versions.

Related errors

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