affaan-m/ECC · error

Canonical session snapshot requires

Error message

Canonical session snapshot requires ${fieldPath} to be an array of strings

What it means

ensureArrayOfStrings requires the field to be an Array whose every element is a string. This error fires when the field is not an array at all or contains at least one non-string element. It guards list-shaped snapshot fields (e.g. tags, worker ids) so consumers can safely .map over strings.

Solutions

1. Ensure the field is an array: wrap single values ([value]) if a scalar was supplied
2. Map elements to strings (arr.map(String)) or filter out non-strings if that is semantically safe
3. Fix the upstream producer to emit string[] JSON
4. Regenerate the snapshot via the correct normalize* adapter

Example fix

// before
snapshot.tags = 'primary';
// after
snapshot.tags = ['primary'];

const okArr = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');

const isArrayOfStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');

try { persistCanonicalSnapshot(s); } catch (e) { if (/array of strings/.test(e.message)) { /* wrap or map */ } else throw e; }

When it happens

Trigger: A snapshot passed to validateCanonicalSnapshot (via persistCanonicalSnapshot or normalize* adapters) has a list field set to a string, object, null, or an array containing numbers/nulls/objects.

Common situations: JSON config where a single value was given instead of a list ("tags": "a" vs "tags": ["a"]); deserializing a Set (non-JSON) into the snapshot; mixing numeric ids into a string array from another tool's output.

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 workers to be an array
• spec.schedule[ ] must be a dense six-cell 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/e4552d2eed77fadd. Report an issue: GitHub.

Appendix: source

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

    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a string`);
  }
}

function ensureOptionalString(value, fieldPath) {
  if (value !== null && value !== undefined && typeof value !== 'string') {
    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a string or null`);
  }
}

function ensureBoolean(value, fieldPath) {
  if (typeof value !== 'boolean') {
    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a boolean`);
  }
}

function ensureArrayOfStrings(value, fieldPath) {
  if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
    throw new Error(`Canonical session snapshot requires ${fieldPath} to be an array of strings`);
  }
}

function ensureInteger(value, fieldPath) {
  if (!Number.isInteger(value) || value < 0) {
    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a non-negative integer`);
  }
}

const STALE_THRESHOLD_MS = 5 * 60 * 1000;

function parseUpdatedMs(updated) {
  if (typeof updated !== 'string' || updated.length === 0) return null;
  const ms = Date.parse(updated);
  return Number.isNaN(ms) ? null : ms;
}

function deriveWorkerHealth(rawWorker) {

View on GitHub (pinned to 8321021c54)