affaan-m/ECC · error · Error

Canonical session snapshot requires workers to be an array

Error message

Canonical session snapshot requires workers to be an array

What it means

validateCanonicalSnapshot requires snapshot.workers to be an array (worker entries are then validated per index). This error throws when workers is null, undefined, an object, or a string. Even a snapshot with no workers must supply an empty array, not omit the key.

Solutions

Set snapshot.workers = [] when there are no workers
Wrap a single worker in an array: workers = [worker]
Ensure workers is a plain JSON array (convert Maps/Sets with Array.from)
Regenerate the snapshot through the appropriate normalize* adapter

Example fix

// before
{ "session": {...}, "workers": null }
// after
{ "session": {...}, "workers": [] }

Defensive patterns

Strategy: type-guard

Validate before calling

if (!hasWorkersArray(snap)) throw new TypeError('workers must be an array');

Type guard

const hasWorkersArray = (v) => Array.isArray(v?.workers);

Try / catch

try { persistCanonicalSnapshot(snap); } catch (e) { if (/workers to be an array/.test(e.message)) { snap.workers = snap.workers ? [snap.workers] : []; } else throw e; }

Prevention

Default workers to []
Never set workers to null

When it happens

Trigger: Building a snapshot without a workers key; JSON where workers was null; passing a single worker object instead of an array containing it; a Map or Set being serialized into an object shape.

Common situations: Test fixtures that omit workers; hand-written snapshots; older schema versions where workers was optional; merging partial snapshots that overwrite workers with null.

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

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

Appendix: source

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

  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');
  }

  snapshot.workers.forEach((worker, index) => {
    if (!isObject(worker)) {
      throw new Error(`Canonical session snapshot requires workers[${index}] to be an object`);
    }

    ensureString(worker.id, `workers[${index}].id`);
    ensureString(worker.label, `workers[${index}].label`);
    ensureString(worker.state, `workers[${index}].state`);
    ensureString(worker.health, `workers[${index}].health`);
    ensureOptionalString(worker.branch, `workers[${index}].branch`);
    ensureOptionalString(worker.worktree, `workers[${index}].worktree`);

    if (!isObject(worker.runtime)) {
      throw new Error(`Canonical session snapshot requires workers[${index}].runtime to be an object`);
    }

View on GitHub (pinned to 8321021c54)