affaan-m/ECC · error

Canonical session snapshot requires

Error message

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

What it means

ensureBoolean requires the named snapshot field to be exactly a JavaScript boolean (typeof === 'boolean'). The library throws this when a boolean-flagged field (e.g. session state flags) carries a truthy number, string like "true", or null. Canonical snapshots use strict types so all consumers can switch on the value without coercion.

Solutions

1. Locate the field from ${fieldPath} and convert it to a real boolean (value === 'true', Boolean(value) as appropriate)
2. Fix the producer (adapter or script) to emit native booleans
3. Validate the raw input before constructing the snapshot object
4. Regenerate the snapshot with the official normalize* functions

Example fix

// before
snapshot.session.isFocused = 'true';
// after
snapshot.session.isFocused = true;

const okBool = (v) => typeof v === 'boolean';

const isBoolean = (v) => typeof v === 'boolean';

try { persistCanonicalSnapshot(s); } catch (e) { if (/to be a boolean/.test(e.message)) { /* coerce */ } else throw e; }

When it happens

Trigger: persistCanonicalSnapshot or a normalize* adapter receives a snapshot where a boolean field holds 0/1, "true"/"false" strings, or null — typical when data round-trips through JSON config or shell output.

Common situations: Reading flags from CLI output or environment variables where everything is a string; YAML parsing "yes"/"no" into strings; older schema versions using 0/1 integers.

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
• requires_alpha must be boolean

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

Appendix: source

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

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

const STALE_THRESHOLD_MS = 5 * 60 * 1000;

function parseUpdatedMs(updated) {

View on GitHub (pinned to 8321021c54)