affaan-m/ECC · error · Error

Unknown state-store schema entity

Error message

Unknown state-store schema entity: ${entityName}

What it means

getEntityValidator looks up the JSON schema definition for a state-store entity by name. It throws when the entity name is not registered in ENTITY_DEFINITIONS or the loaded schema lacks the corresponding $defs entry, so callers never get a validator built from a missing schema.

Solutions

1. Correct the entityName to one of the supported entities (e.g. decision, governanceEvent, skillRun, installState, workItem, session).
2. Regenerate/update the state-store JSON schema so $defs contains the mapped definition.
3. Clear any stale cached schema file that the reader resolves.
4. Check the ENTITY_DEFINITIONS mapping to confirm the exact accepted name spelling.

Example fix

// before
validateEntity('workitems', payload);
// after
validateEntity('workItem', payload);

const KNOWN = ['decision','governanceEvent','skillRun','installState','workItem','session'];
if (!KNOWN.includes(entityName)) throw new Error(`Unsupported entity: ${entityName}`);

const isKnownEntity = (n) => typeof n === 'string' && n in ENTITY_DEFINITIONS;

try {
  const v = getEntityValidator(entityName);
} catch (e) {
  if (String(e.message).startsWith('Unknown state-store schema entity')) {
    console.error(`Check entity name spelling and schema version: ${entityName}`);
  }
  throw e;
}

When it happens

Trigger: Calling getEntityValidator('typoEntity') or validator('unknown') with a name not present in ENTITY_DEFINITIONS; or the schema file failed to load/is stale so schema.$defs is missing the definition even though the name is registered.

Common situations: Typos in the entity name string; a new entity type added to ENTITY_DEFINITIONS but the bundled schema JSON was not regenerated; an old cached schema version after an upgrade.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Invalid )` : ''}
• -32602
• artifact path must be a non-empty relative path
• assets must be a nonempty list
• built an invalid spec

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

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