affaan-m/ECC · error

Canonical session snapshot requires

Error message

Canonical session snapshot requires ${fieldPath} to be a string

What it means

validateCanonicalSnapshot calls ensureStringAllowEmpty for fields that must be strings but may be empty. This error means one of those field paths held a non-string value (number, boolean, object, null, or undefined). The library throws it eagerly while validating a canonical session snapshot before persisting or normalizing it.

Solutions

1. Log the full snapshot and find the field named in ${fieldPath} in the error message
2. Coerce or fix that field to a string (String(value), or null handling upstream)
3. If the field is genuinely optional, use null with the ensureOptionalString-validated path rather than undefined
4. Regenerate the snapshot via the official normalize* adapter functions instead of hand-constructing it

Example fix

// before
snapshot.session.repoRoot = undefined;
// after
snapshot.session.repoRoot = '/worktrees/my-repo';

const ok = typeof snapshot?.schemaVersion === 'string' && typeof snapshot?.adapterId === 'string';

const isString = (v) => typeof v === 'string';

try { persistCanonicalSnapshot(s); } catch (e) { if (/to be a string/.test(e.message)) { console.error(e.message); } else throw e; }

When it happens

Trigger: Calling persistCanonicalSnapshot or any normalize* function with a snapshot where an allow-empty string field (validated via ensureStringAllowEmpty in canonical-session.js) is set to null, undefined, a number, or an object.

Common situations: Hand-written snapshot JSON where a field like session.repoRoot or a session id was omitted or typed as a number; adapters built against an older schema version; deserialized JSON from an external tool where empty fields became 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

• Canonical session snapshot must be an object
• Canonical session snapshot requires
• Canonical session snapshot requires
• Invalid managed hook handler at
• spec.schedule must be an array of six-cell rows

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

Appendix: source

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

  if (typeof context !== 'string' || context.trim().length === 0) {
    return [];
  }

  return context
    .split('\n')
    .map(line => line.trim())
    .filter(Boolean);
}

function ensureString(value, fieldPath) {
  if (typeof value !== 'string' || value.length === 0) {
    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a non-empty string`);
  }
}

function ensureStringAllowEmpty(value, fieldPath) {
  if (typeof value !== 'string') {
    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`);

View on GitHub (pinned to 8321021c54)