ruvnet/ruflo · error

Unsupported artifact ledger version: ${data.version} (expect

Error message

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

What it means

SerializedArtifactLedger payloads carry a SERIALIZATION_VERSION stamp (currently 1) written at export() time; import() rejects any payload whose version differs so a schema change cannot silently corrupt the ledger. This is a forward/backward-compatibility gate: the export and the importing code must come from the same serialization generation.

Source

Thrown at v3/@claude-flow/guidance/src/artifacts.ts:429

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

  /**
   * Import a previously exported ledger, replacing all current contents.
   *
   * @param data - Serialized ledger data
   * @throws If the version is unsupported
   */
  import(data: SerializedArtifactLedger): void {
    if (data.version !== SERIALIZATION_VERSION) {
      throw new Error(
        `Unsupported artifact ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})`,
      );
    }
    this.artifacts.clear();
    for (const artifact of data.artifacts) {
      this.artifacts.set(artifact.artifactId, { ...artifact });
    }
  }

  /**
   * Get aggregate statistics about the ledger.
   *
   * @returns Counts by kind and total content size
   */
  getStats(): ArtifactStats {
    const byKind = Object.fromEntries(
      ALL_KINDS.map(k => [k, 0]),
    ) as Record<ArtifactKind, number>;

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Re-export the ledger using the same package version that will import it
2. Pin both environments (source and target) to the same @claude-flow/guidance version
3. Write a one-off migration that reads the old-version payload and re-records artifacts into a fresh ledger via record(), then export
4. Validate `data.version` before calling import() and skip stale files

Example fix

// before
ledger.import(jsonFromFile); // throws if exported by an older version

// after
if (jsonFromFile.version !== ledger.export().version) {
  // regenerate the dump with the current version, or migrate
} else {
  ledger.import(jsonFromFile);
}

const currentVersion = ledger.export().version;
if (data.version !== currentVersion) {
  // stale or future payload — skip import, migrate, or regenerate
}

try {
  ledger.import(data);
} catch (err) {
  if (err instanceof Error && err.message.includes('Unsupported artifact ledger version')) {
    // keep current ledger contents; re-export from the matching package version
  } else throw err;
}

When it happens

Trigger: Exporting a ledger with @claude-flow/guidance@X and importing it under version Y after SERIALIZATION_VERSION changed; hand-editing the exported JSON; truncated or partially written export files where the version field is wrong.

Common situations: Upgrading the guidance package across a serialization format bump; copying ledger dumps between staging and production running different package versions; restoring old backups.

Related errors

• Unsupported proof chain version: ${data.version} (expected $
• Unsupported temporal store version: ${data.version} (expecte
• Unsupported uncertainty ledger version: ${data.version} (exp
• abBenchmark requires a content-aware executor. The provided
• ArtifactLedger requires an explicit signingKey — hardcoded d

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