affaan-m/ECC · error

Unsupported canonical session schema version

Error message

Unsupported canonical session schema version: ${snapshot.schemaVersion}

What it means

Canonical snapshots are versioned via schemaVersion, which must equal the library's SESSION_SCHEMA_VERSION constant. This error throws when schemaVersion is a string (that check passed) but does not match the supported version — e.g. a snapshot written by an older or newer adapter build. It prevents silently misinterpreting a differently-shaped snapshot.

Solutions

1. Check the required version (SESSION_SCHEMA_VERSION) in canonical-session.js and the value in your snapshot
2. Re-run the original source through the current normalize* adapter to regenerate the snapshot with the correct schemaVersion
3. Migrate or delete stale on-disk snapshots from the older version
4. Update the library if your snapshot uses a newer schema than the installed code

Example fix

// before
{ "schemaVersion": "1", "adapterId": "dmux" }
// after
{ "schemaVersion": "2.0", "adapterId": "dmux" } // match SESSION_SCHEMA_VERSION

if (snap.schemaVersion !== SESSION_SCHEMA_VERSION) throw new Error('schema version mismatch');

const hasSupportedSchema = (v) => v?.schemaVersion === SESSION_SCHEMA_VERSION;

try { persistCanonicalSnapshot(snap); } catch (e) { if (/Unsupported canonical session schema version/.test(e.message)) { snap = regenerate(raw); } else throw e; }

When it happens

Trigger: Reading a snapshot file persisted by a previous library version; hand-writing schemaVersion (or omitting the '1.0'-style value); a forward/backward incompatibility after upgrading the repo scripts.

Common situations: Upgrading the toolchain while old session files remain on disk; merging snapshots from different branches with divergent schema versions; typos in a hand-crafted snapshot like "schemaVersion": 2 (a number, or wrong string).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unsupported asset receipt schema
• -32602
• artifact path must be a non-empty relative path
• assets must be a nonempty list
• built an invalid spec

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/b32ba11d1b1bef24. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/session-adapters/canonical-session.js:169

  const completedCount = (workerStates.completed || 0)
    + (workerStates.succeeded || 0)
    + (workerStates.success || 0)
    + (workerStates.done || 0);
  if (completedCount === totalWorkers) {
    return 'completed';
  }

  return 'idle';
}

function validateCanonicalSnapshot(snapshot) {
  if (!isObject(snapshot)) {
    throw new Error('Canonical session snapshot must be an object');
  }

  ensureString(snapshot.schemaVersion, 'schemaVersion');
  if (snapshot.schemaVersion !== SESSION_SCHEMA_VERSION) {
    throw new Error(`Unsupported canonical session schema version: ${snapshot.schemaVersion}`);
  }

  ensureString(snapshot.adapterId, 'adapterId');

  if (!isObject(snapshot.session)) {
    throw new Error('Canonical session snapshot requires session to be an object');
  }

  ensureString(snapshot.session.id, 'session.id');
  ensureString(snapshot.session.kind, 'session.kind');
  ensureString(snapshot.session.state, 'session.state');
  ensureOptionalString(snapshot.session.repoRoot, 'session.repoRoot');

  if (!isObject(snapshot.session.sourceTarget)) {
    throw new Error('Canonical session snapshot requires session.sourceTarget to be an object');
  }

  ensureString(snapshot.session.sourceTarget.type, 'session.sourceTarget.type');

View on GitHub (pinned to 8321021c54)