affaan-m/ECC · error · Error

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

Error message

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

What it means

Thrown by the ensureString helper inside validateCanonicalSnapshot (and the normalize*/persist functions that call it) when a required canonical-session field is missing, empty, or not a string. Used for schemaVersion, adapterId, session.id, session.kind, session.state, session.sourceTarget.type/value, and worker id/label/state/health.

Source

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

    .trim()
    .replace(/[^A-Za-z0-9._-]+/g, '_')
    .replace(/^_+|_+$/g, '') || 'unknown';
}

function parseContextSeedPaths(context) {
  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`);

View on GitHub (pinned to 01e15490f0)

Solutions

Ensure every required string field is populated with a non-empty value before calling persistCanonicalSnapshot or a normalize function.
Run validateCanonicalSnapshot(snapshot) early during adapter development to catch missing fields.
Default-coalesce required fields from available data (e.g. worker.id from a slug).
Cross-check against SESSION_SCHEMA_VERSION ('ecc.session.v1') required fields in the validator.

Example fix

// before
persistCanonicalSnapshot({ schemaVersion: '', adapterId: 'x', session: { ... } });

// after
persistCanonicalSnapshot({
  schemaVersion: SESSION_SCHEMA_VERSION,
  adapterId: 'x',
  session: { id: 'real-id', kind: 'history', state: 'recorded', ... },
  ...
});

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check required non-empty string fields before persisting.
const required = [snapshot.schemaVersion, snapshot.adapterId, snapshot.session && snapshot.session.id];
if (required.some(v => typeof v !== 'string' || v.length === 0)) {
  throw new Error('Snapshot is missing required string fields');
}
persistCanonicalSnapshot(snapshot);

Type guard

function hasRequiredStrings(s) {
  return s && typeof s === 'object'
    && typeof s.schemaVersion === 'string' && s.schemaVersion.length > 0
    && typeof s.adapterId === 'string' && s.adapterId.length > 0;
}

Prevention

Use the exported normalize* helpers which populate required fields.
Reference SESSION_SCHEMA_VERSION instead of hardcoding the version string.
Run validateCanonicalSnapshot during adapter development to catch gaps.

When it happens

Trigger: A snapshot object where schemaVersion is undefined, session.id is an empty string, a worker is missing its label, or any required string field was set to null. Commonly hit when an adapter builds a snapshot and forgets to populate a required field, or when persisting a hand-constructed object.

Common situations: A new adapter that does not yet set all required fields; a session record from an older CLI version missing id/kind/state; an empty string where the schema requires content; a field accidentally deleted during normalization.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/c6b4f58147838d55. Report an issue: GitHub.