What causes "Unknown state-store schema entity: ${entityName}" in affaan-m/ECC?

Use one of the seven defined entity names exactly: session, skillRun, skillVersion, decision, installState, governanceEvent, workItem.

affaan-m/ECC · error

Unknown state-store schema entity: ${entityName}

Error message

Unknown state-store schema entity: ${entityName}

What it means

Thrown by getEntityValidator() in the state-store schema module when entityName is not a key in the ENTITY_DEFINITIONS map (session, skillRun, skillVersion, decision, installState, governanceEvent, workItem) or when the corresponding $defs entry is missing from the loaded JSON schema. The module compiles and caches an AJV validator per entity, so an unknown name is a programmer error rather than a runtime data error.

Source

Thrown at scripts/lib/state-store/schema.js:53

  }

  cachedAjv = new Ajv({
    allErrors: true,
    strict: false,
  });
  return cachedAjv;
}

function getEntityValidator(entityName) {
  if (cachedValidators.has(entityName)) {
    return cachedValidators.get(entityName);
  }

  const schema = readSchema();
  const definitionName = ENTITY_DEFINITIONS[entityName];

  if (!definitionName || !schema.$defs || !schema.$defs[definitionName]) {
    throw new Error(`Unknown state-store schema entity: ${entityName}`);
  }

  const validatorSchema = {
    $schema: schema.$schema,
    ...schema.$defs[definitionName],
    $defs: schema.$defs,
  };
  const validator = getAjv().compile(validatorSchema);
  cachedValidators.set(entityName, validator);
  return validator;
}

function formatValidationErrors(errors = []) {
  return errors
    .map(error => `${error.instancePath || '/'} ${error.message}`)
    .join('; ');
}

View on GitHub (pinned to 01e15490f0)

Solutions

Use one of the seven defined entity names exactly: session, skillRun, skillVersion, decision, installState, governanceEvent, workItem.
Import ENTITY_DEFINITIONS (or mirror its keys) and validate the name against Object.keys(ENTITY_DEFINITIONS) before calling.
If you genuinely need a new entity, add it to ENTITY_DEFINITIONS in scripts/lib/state-store/schema.js and add a matching $defs entry in schemas/state-store.schema.json.
Check casing: the names are camelCase, not PascalCase or kebab-case.

Example fix

// before
assertValidEntity('Sessions', row);  // -> Unknown state-store schema entity: Sessions

// after
const ENTITY_DEFINITIONS = require('scripts/lib/state-store/schema');
// or import the map directly if exposed
assertValidEntity('session', row);

Defensive patterns

Strategy: type-guard

Validate before calling

const ENTITY_DEFINITIONS = {
  session: 'session', skillRun: 'skillRun', skillVersion: 'skillVersion',
  decision: 'decision', installState: 'installState',
  governanceEvent: 'governanceEvent', workItem: 'workItem',
};

function assertKnownEntity(entityName) {
  if (!Object.prototype.hasOwnProperty.call(ENTITY_DEFINITIONS, entityName)) {
    throw new Error(`Unsupported entity: ${entityName}. Known: ${Object.keys(ENTITY_DEFINITIONS).join(', ')}`);
  }
}

assertKnownEntity(entityName);
assertValidEntity(entityName, payload);

Type guard

const KNOWN_ENTITIES = new Set(['session','skillRun','skillVersion','decision','installState','governanceEvent','workItem']);

function isStateStoreEntity(name) {
  return typeof name === 'string' && KNOWN_ENTITIES.has(name);
}

Try / catch

try {
  assertValidEntity(entityName, payload);
} catch (error) {
  if (/Unknown state-store schema entity/.test(error.message)) {
    // programmer error: log and re-throw with the list of valid names
    throw new Error(`${error.message}. Valid: ${[...KNOWN_ENTITIES].join(', ')}`);
  }
  throw error;
}

Prevention

Treat the entity name as a constant — never derive it from user input.
Mirror ENTITY_DEFINITIONS keys in your own code and unit-test that they stay in sync.
When you add a new entity, ship the schema $defs entry in the same commit.
Use TypeScript / JSDoc to narrow the type so the typo is caught at edit time.

When it happens

Trigger: Calling assertValidEntity('sessions', payload) (plural); calling validateEntity('task', payload) for a type that has no schema; typo like 'skilRun'; calling with a name whose definition was removed from state-store.schema.json; calling before the schema file is shipped (readSchema would have thrown earlier, but a missing $defs entry triggers this).

Common situations: Refactor renames an entity in the schema but callers still use the old name; a downstream feature assumes a new entity exists before the schema migration landed; copy-paste from a different version of the docs; IDE autocomplete suggests a similar-but-wrong name.

Related errors

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