{"record":{"id":"48f1e8cb170e7d48","repo":"affaan-m/ECC","slug":"unknown-state-store-schema-entity-entityname","errorCode":null,"errorMessage":"Unknown state-store schema entity: ${entityName}","messagePattern":"Unknown state-store schema entity: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/state-store/schema.js","lineNumber":53,"sourceCode":"  }\n\n  cachedAjv = new Ajv({\n    allErrors: true,\n    strict: false,\n  });\n  return cachedAjv;\n}\n\nfunction getEntityValidator(entityName) {\n  if (cachedValidators.has(entityName)) {\n    return cachedValidators.get(entityName);\n  }\n\n  const schema = readSchema();\n  const definitionName = ENTITY_DEFINITIONS[entityName];\n\n  if (!definitionName || !schema.$defs || !schema.$defs[definitionName]) {\n    throw new Error(`Unknown state-store schema entity: ${entityName}`);\n  }\n\n  const validatorSchema = {\n    $schema: schema.$schema,\n    ...schema.$defs[definitionName],\n    $defs: schema.$defs,\n  };\n  const validator = getAjv().compile(validatorSchema);\n  cachedValidators.set(entityName, validator);\n  return validator;\n}\n\nfunction formatValidationErrors(errors = []) {\n  return errors\n    .map(error => `${error.instancePath || '/'} ${error.message}`)\n    .join('; ');\n}\n","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/state-store/schema.js#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the entityName to one of the supported entities (e.g. decision, governanceEvent, skillRun, installState, workItem, session).","Regenerate/update the state-store JSON schema so $defs contains the mapped definition.","Clear any stale cached schema file that the reader resolves.","Check the ENTITY_DEFINITIONS mapping to confirm the exact accepted name spelling."],"exampleFix":"// before\nvalidateEntity('workitems', payload);\n// after\nvalidateEntity('workItem', payload);","handlingStrategy":"validation","validationCode":"const KNOWN = ['decision','governanceEvent','skillRun','installState','workItem','session'];\nif (!KNOWN.includes(entityName)) throw new Error(`Unsupported entity: ${entityName}`);","typeGuard":"const isKnownEntity = (n) => typeof n === 'string' && n in ENTITY_DEFINITIONS;","tryCatchPattern":"try {\n  const v = getEntityValidator(entityName);\n} catch (e) {\n  if (String(e.message).startsWith('Unknown state-store schema entity')) {\n    console.error(`Check entity name spelling and schema version: ${entityName}`);\n  }\n  throw e;\n}","preventionTips":["Keep entity names in a single exported constant list and import it.","Regenerate the JSON schema whenever ENTITY_DEFINITIONS changes.","Use an enum/union type instead of free-form strings for entity names.","Pin the schema file version alongside the code version."],"tags":["schema","validation","state-store"],"backgroundTag":"entity-not-found","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}