affaan-m/ECC · error · Error

Canonical session snapshot requires workers

Error message

Canonical session snapshot requires workers[${index}].artifacts to be an object

What it means

This error is thrown when a worker entry lacks an artifacts object. The canonical schema ends each worker validation with workers[i].artifacts being a plain object (contents otherwise unconstrained), used to record files or references produced by the worker. The validator refuses snapshots where artifacts is missing or not an object.

Solutions

Set worker.artifacts = {} (or the actual artifact map) on the offending worker.
Update the producer so every worker is initialized with an empty artifacts object.
Regenerate the snapshot with current adapters.
Assert validateCanonicalSnapshot passes on all persisted fixtures in tests.

Example fix

// before
worker.artifacts = [];
// after
worker.artifacts = {};

Defensive patterns

Strategy: validation

Validate before calling

const artifactsOk = snapshot.workers.every(w => w && typeof w.artifacts === 'object' && w.artifacts !== null && !Array.isArray(w.artifacts));
if (!artifactsOk) throw new Error('every worker needs an artifacts object');

Type guard

function hasArtifacts(w) { return !!w && typeof w.artifacts === 'object' && w.artifacts !== null && !Array.isArray(w.artifacts); }

Try / catch

try { persistCanonicalSnapshot(snapshot); } catch (err) { if (String(err.message).includes('.artifacts to be an object')) { console.error('Worker missing artifacts block:', err.message); /* set artifacts = {} and retry */ } else { throw err; } }

Prevention

Always initialize worker.artifacts = {} at creation.
Use plain objects (not arrays or Maps) for artifacts.
Validate snapshots after any transform that rebuilds workers.
Prefer regenerate-over-patch for snapshots from older formats.

When it happens

Trigger: Calling persistCanonicalSnapshot or any normalize*Session adapter with a worker whose artifacts field is absent, null, an array, or a primitive.

Common situations: Adapters predating the artifacts requirement; snapshots hand-assembled in scripts or tests; JSON round-trips where artifacts was dropped by a lossy transform.

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/4519e427d912f10d. Report an issue: GitHub.

Appendix: source

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

    ensureBoolean(worker.runtime.dead, `workers[${index}].runtime.dead`);

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

    ensureStringAllowEmpty(worker.intent.objective, `workers[${index}].intent.objective`);
    ensureArrayOfStrings(worker.intent.seedPaths, `workers[${index}].intent.seedPaths`);

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

    ensureArrayOfStrings(worker.outputs.summary, `workers[${index}].outputs.summary`);
    ensureArrayOfStrings(worker.outputs.validation, `workers[${index}].outputs.validation`);
    ensureArrayOfStrings(worker.outputs.remainingRisks, `workers[${index}].outputs.remainingRisks`);

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

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

  ensureInteger(snapshot.aggregates.workerCount, 'aggregates.workerCount');
  if (snapshot.aggregates.workerCount !== snapshot.workers.length) {
    throw new Error('Canonical session snapshot requires aggregates.workerCount to match workers.length');
  }

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

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

View on GitHub (pinned to 8321021c54)