Canonical session snapshot requires

Error message

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

What it means

ensureOptionalString validates that a snapshot field is either a string or null. This error means the field at fieldPath was set to some other type (number, boolean, object, or undefined is allowed only via the explicit null/undefined check — actually undefined passes, so this fired on a concrete non-string value). It keeps the canonical snapshot schema strict so downstream consumers can rely on string|null types.

Solutions

Inspect the fieldPath named in the error and print its type (typeof snapshot.session.repoRoot)
Convert the value to its string form (path.toString(), String(value)) before normalizing
Use null explicitly for absent values instead of numbers/objects
Re-run the snapshot through the matching normalize* adapter for your source format

Example fix

// before
snapshot.session.repoRoot = { path: '/repo' };
// after
snapshot.session.repoRoot = '/repo';

Defensive patterns

Strategy: validation

Validate before calling

const okOpt = (v) => v === null || typeof v === 'string';

Type guard

const isOptionalString = (v) => v == null || typeof v === 'string';

Try / catch

try { persistCanonicalSnapshot(s); } catch (e) { if (/string or null/.test(e.message)) { /* coerce */ } else throw e; }

Prevention

Use null for absent optionals
Coerce config values to strings at boundaries

When it happens

Trigger: Calling validateCanonicalSnapshot (via persistCanonicalSnapshot or a normalize* adapter) with an optional string field such as session.repoRoot set to e.g. 42 or { raw: '...' } instead of a string or null.

Common situations: Mapping an object (like a worktree handle) into repoRoot instead of its path string; adapters reading config where a path field was parsed as YAML/JSON with a non-string type; older adapter versions producing different field shapes.

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

Appendix: source

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

    .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`);
  }
}

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

View on GitHub (pinned to 8321021c54)