affaan-m/ECC · error · Error

Canonical session snapshot requires session to be an object

Error message

Canonical session snapshot requires session to be an object

What it means

Thrown by validateCanonicalSnapshot when snapshot.session is not a plain object. The session sub-object carries id, kind, state, repoRoot, and sourceTarget, all of which are required for a canonical snapshot to be meaningful.

Source

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

  }

  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');
  ensureString(snapshot.session.sourceTarget.value, 'session.sourceTarget.value');

  if (!Array.isArray(snapshot.workers)) {
    throw new Error('Canonical session snapshot requires workers to be an array');
  }

View on GitHub (pinned to 01e15490f0)

Solutions

Always construct the session object explicitly with id/kind/state/sourceTarget.
Validate presence of snapshot.session as an object before calling validateCanonicalSnapshot.
Use the exported normalize* helpers, which build the session block for you.

Example fix

// before
validateCanonicalSnapshot({ schemaVersion, adapterId, workers: [] }); // no session

// after
validateCanonicalSnapshot({
  schemaVersion, adapterId,
  session: { id, kind, state, repoRoot: null, sourceTarget },
  workers: [],
  aggregates: buildAggregates([])
});

Defensive patterns

Strategy: type-guard

Validate before calling

if (!snapshot.session || typeof snapshot.session !== 'object' || Array.isArray(snapshot.session)) {
  throw new Error('snapshot.session must be an object');
}

Type guard

function hasSessionObject(s) {
  return s && typeof s === 'object' && !Array.isArray(s)
    && s.session && typeof s.session === 'object' && !Array.isArray(s.session);
}

Prevention

Always construct the session block explicitly in normalize functions.
Include id, kind, state, repoRoot, and sourceTarget when building it.

When it happens

Trigger: A snapshot where session is null, undefined, an array, or a string. Happens when an adapter omits the session block or assigns it to a primitive by mistake.

Common situations: A normalize function that forgot to include the session key; a hand-edited snapshot missing the session object; a transform that flattened session fields into the top level.

Related errors

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