affaan-m/ECC · error · Error

Unsupported canonical session schema version: ${snapshot.sch

Error message

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

What it means

Thrown by validateCanonicalSnapshot when snapshot.schemaVersion is a non-empty string but does not equal the supported SESSION_SCHEMA_VERSION ('ecc.session.v1'). This guards against snapshots produced by a future or incompatible schema version being interpreted by this code.

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 01e15490f0)

Solutions

Always set schemaVersion to SESSION_SCHEMA_VERSION (exported from the module) when building snapshots.
Before reading a recording, check its schemaVersion and migrate or skip incompatible versions.
Regenerate stale recordings under the current CLI rather than patching the version string.

Example fix

// before
const snap = { schemaVersion: '1.0', ... };
validateCanonicalSnapshot(snap);

// after
const { SESSION_SCHEMA_VERSION } = require('./canonical-session');
const snap = { schemaVersion: SESSION_SCHEMA_VERSION, ... };
validateCanonicalSnapshot(snap);

Defensive patterns

Strategy: validation

Validate before calling

const { SESSION_SCHEMA_VERSION } = require('./canonical-session');
if (parsed.schemaVersion !== SESSION_SCHEMA_VERSION) {
  // migrate or skip, do not validate under this code
  return null;
}
validateCanonicalSnapshot(parsed);

Prevention

Always set schemaVersion to the exported SESSION_SCHEMA_VERSION constant.
Gate reading old recordings on a version check and migrate explicitly.
Never guess or invent a version string.

When it happens

Trigger: A snapshot whose schemaVersion is 'ecc.session.v2', '1.0', a typo, or any value other than 'ecc.session.v1'. Common when reading a recording written by a newer/older CLI, or a hand-built fixture with a guessed version.

Common situations: Upgrading the CLI and reading old recordings written under a different version label; downgrading; interop with a fork that uses a different version string; a test fixture with an invented schemaVersion.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/b32ba11d1b1bef24. Report an issue: GitHub.