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

After the top-level and schemaVersion checks, validateCanonicalSnapshot requires snapshot.session to be an object holding id/kind/state etc. This error throws when session is null, undefined, an array, or a non-object. The nested session record is mandatory in the canonical shape.

Solutions

1. Add the session object with required fields id, kind, state, repoRoot, sourceTarget
2. Regenerate via the matching normalize* adapter (normalizeDmuxSnapshot, normalizeOpencodeSession, etc.) instead of hand-assembling
3. If migrating from a flattened layout, move top-level fields into snapshot.session
4. Validate the JSON file you are loading actually contains a session object

Example fix

// before
{ "schemaVersion": "2.0", "adapterId": "opencode", "workers": [] }
// after
{ "schemaVersion": "2.0", "adapterId": "opencode", "session": { "id": "s1", "kind": "opencode", "state": "idle", "repoRoot": null, "sourceTarget": { "type": "path", "value": "/repo" } }, "workers": [] }

if (!hasSessionObject(snap)) throw new TypeError('Missing session object');

const hasSessionObject = (v) => typeof v?.session === 'object' && v.session !== null && !Array.isArray(v.session);

try { persistCanonicalSnapshot(snap); } catch (e) { if (/session to be an object/.test(e.message)) { snap = normalizeAdapter(raw); } else throw e; }

When it happens

Trigger: Constructing a snapshot without a session key; JSON deserialization where session was null; passing only metadata like { schemaVersion, adapterId, workers }; destructuring bugs that drop the session field.

Common situations: Hand-built snapshots missing the nested object; adapters from older schema versions that flattened session fields to the top level; partial updates that serialized only changed top-level fields.

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

• Canonical session snapshot requires session.sourceTarget to…
• Canonical session snapshot requires workers to be an array
• -32602
• artifact path must be a non-empty relative path
• assets must be a nonempty list

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

Appendix: 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 8321021c54)