ruvnet/ruflo · error

Unsupported proof chain version: ${data.version} (expected $

Error message

Unsupported proof chain version: ${data.version} (expected ${SERIALIZATION_VERSION})

What it means

ProofChain.import() restores a chain only from SerializedProofChain objects whose version equals the module's SERIALIZATION_VERSION (currently 1); export() stamps that version at export time. A mismatch means the serialized data was produced by a different release of @claude-flow/guidance (older or newer), or the payload was hand-edited/corrupted. The expected and actual versions are both included in the message.

Source

Thrown at v3/@claude-flow/guidance/src/proof.ts:302

  /**
   * Export the chain as a serializable object.
   */
  export(): SerializedProofChain {
    return {
      envelopes: this.envelopes.map(e => ({ ...e })),
      createdAt: new Date().toISOString(),
      version: SERIALIZATION_VERSION,
    };
  }

  /**
   * Restore the chain from a previously exported object.
   *
   * Replaces the current chain contents entirely.
   */
  import(data: SerializedProofChain): void {
    if (data.version !== SERIALIZATION_VERSION) {
      throw new Error(
        `Unsupported proof chain version: ${data.version} (expected ${SERIALIZATION_VERSION})`,
      );
    }
    this.envelopes = data.envelopes.map(e => ({ ...e }));
  }

  // ===========================================================================
  // Private helpers
  // ===========================================================================

  /**
   * Compute the SHA-256 content hash of a RunEvent.
   */
  private computeContentHash(event: RunEvent): string {
    const payload = JSON.stringify(event, Object.keys(event).sort());
    return createHash('sha256').update(payload).digest('hex');
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Pin the same @claude-flow/guidance version in every environment that writes and reads chain data
2. Before import(), check (data as SerializedProofChain).version — currently 1 — and reject or migrate mismatches explicitly
3. To migrate, verify the chain with the version that produced it, then re-append or re-export under the current version
4. If provenance cannot be established, start a fresh chain rather than importing unverifiable data

Example fix

// before
chain.import(JSON.parse(await readFile('chain.json', 'utf-8'))); // version mismatch -> throws
// after
const data = JSON.parse(await readFile('chain.json', 'utf-8')) as SerializedProofChain;
if (data.version !== 1) {
  throw new Error(`Chain file version ${data.version} not supported by this build; migrate it first`);
}
chain.import(data);

function isCompatibleSerializedChain(data: unknown): data is SerializedProofChain {
  return (
    typeof data === 'object' && data !== null &&
    'version' in data && (data as SerializedProofChain).version === 1 &&
    'envelopes' in data && Array.isArray((data as SerializedProofChain).envelopes)
  );
}
const data: unknown = JSON.parse(raw);
if (!isCompatibleSerializedChain(data)) {
  throw new Error(`Chain payload version unsupported; expected 1, got ${(data as { version?: unknown })?.version}`);
}
chain.import(data);

function isCompatibleSerializedChain(data: unknown): data is SerializedProofChain {
  return (
    typeof data === 'object' && data !== null &&
    (data as { version?: unknown }).version === 1 &&
    Array.isArray((data as { envelopes?: unknown }).envelopes)
  );
}

try {
  chain.import(data);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unsupported proof chain version')) {
    // data came from a different library release: pin versions or migrate via the producing version
    throw new Error(`Chain data needs migration before import: ${err.message}`);
  }
  throw err;
}

When it happens

Trigger: Importing chain JSON persisted by a different (older or newer) package version after an upgrade or downgrade; hand-editing an export; loading fixtures created under another release.

Common situations: Upgrading @claude-flow/guidance in one service while another still writes chains with the old version; restoring archived audit chains after a version bump; mixing fixture data across dependency updates.

Related errors

• Unsupported artifact ledger version: ${data.version} (expect
• Unsupported temporal store version: ${data.version} (expecte
• Unsupported uncertainty ledger version: ${data.version} (exp
• abBenchmark requires a content-aware executor. The provided
• ProofChain requires an explicit signingKey — hardcoded defau

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