affaan-m/ECC · error

Canonical session snapshot requires

Error message

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

What it means

ensureString() is the validator used by validateCanonicalSessionSnapshot() to enforce the canonical session snapshot schema: required string fields must be actual non-empty strings. When a field at fieldPath (e.g. 'meta.source', 'session.id') is absent, undefined, not a string, or an empty string, the adapter throws this error naming the exact field path. It protects downstream consumers from malformed imported session data.

Solutions

1. Read the fieldPath in the message and populate that field with a non-empty string in the snapshot JSON.
2. Regenerate the snapshot with the exporting tool at a compatible/recent version so all required fields are emitted.
3. If migrating between harness formats, run the export through the library's current adapter/exporter rather than hand-editing JSON.
4. Check for schema changes: diff your snapshot against the documented canonical snapshot format for the installed version.

Example fix

// before
{ "session": { "id": "", "title": "My session" } }
// throws: requires session.id to be a non-empty string
// after
{ "session": { "id": "a1b2c3d4", "title": "My session" } }

function validateSnapshotBasics(snap) {
  for (const p of [['session', snap.session], ['session.id', snap.session && snap.session.id], ['meta.source', snap.meta && snap.meta.source]]) {
    const [name, val] = p;
    if (typeof val !== 'string' || val.length === 0) {
      throw new Error(`Snapshot field ${name} must be a non-empty string before import`);
    }
  }
}
// run validateSnapshotBaseline(json) before handing the snapshot to the adapter

function isNonEmptyString(v) {
  return typeof v === 'string' && v.length > 0;
}

try {
  validateCanonicalSessionSnapshot(raw);
} catch (e) {
  const m = /requires (.+?) to be a non-empty string/.exec(e.message);
  if (m) {
    console.error(`Snapshot field '${m[1]}' is missing/empty — regenerate the export or fill the field.`);
  } else throw e;
}

When it happens

Trigger: Importing/adapting a session snapshot where a required field is missing or empty: JSON produced by another tool lacking 'meta.source'; a hand-written snapshot with id: ''; a field renamed upstream so the adapter reads undefined; parsing a transcript that yielded null for a field.

Common situations: Cross-harness session migration (Claude/Codex/Cursor exports with differing schemas); older session files predating a schema field addition; truncated or corrupted export files; manually edited session JSON with a blanked field; adapter version older than the snapshot format.

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

• bundle values must be finite JSON data
• Cannot delete active session
• Cannot merge active session
• Cannot rebase active session
• Canonical session snapshot requires aggregates.healths to…

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

Appendix: 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 8321021c54)