{"record":{"id":"71db4f9d4c6a497f","repo":"affaan-m/ECC","slug":"invalid-entityname-label-label","errorCode":null,"errorMessage":"Invalid ${entityName}${label ? ` (${label})` : ''}: ${formatValidationErrors(result.errors)}","messagePattern":"Invalid (.+?)(.+?)\\)` : ''\\}: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/state-store/schema.js","lineNumber":84,"sourceCode":"function formatValidationErrors(errors = []) {\n  return errors\n    .map(error => `${error.instancePath || '/'} ${error.message}`)\n    .join('; ');\n}\n\nfunction validateEntity(entityName, payload) {\n  const validator = getEntityValidator(entityName);\n  const valid = validator(payload);\n  return {\n    valid,\n    errors: validator.errors || [],\n  };\n}\n\nfunction assertValidEntity(entityName, payload, label) {\n  const result = validateEntity(entityName, payload);\n  if (!result.valid) {\n    throw new Error(`Invalid ${entityName}${label ? ` (${label})` : ''}: ${formatValidationErrors(result.errors)}`);\n  }\n}\n\nmodule.exports = {\n  assertValidEntity,\n  formatValidationErrors,\n  readSchema,\n  validateEntity,\n};\n","sourceCodeStart":66,"sourceCodeEnd":94,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/state-store/schema.js#L66-L94","documentation":"Thrown by assertValidEntity() when the AJV validator for the named entity returns invalid for the supplied payload. The message is composed of the entity name, an optional label (used to identify which row/caller failed), and a formatted list of AJV errors (instancePath + message for each). This is the runtime data-quality gate for anything written into the state store.","triggerScenarios":"Inserting a session row whose required fields (e.g. id, harness, state, started_at) are missing or wrongly typed; writing a workItem with a status outside the enum; passing a timestamp that is not an ISO string; payload shape drift after a schema migration that the caller has not caught up to.","commonSituations":"A new required field was added to the schema and old producers still omit it; an upstream adapter normalizes to the wrong casing (snake_case vs camelCase); a nullable column is sent as the string 'null'; test fixtures have drifted from the real schema.","solutions":["Read the AJV errors in the message — each entry shows instancePath (the failing JSON pointer) and the constraint that failed.","Diff your payload against the matching $defs.<entityName> block in schemas/state-store.schema.json.","Use validateEntity(entityName, payload) (non-throwing) to get { valid, errors } and surface them to the caller instead of crashing.","Regenerate fixtures from a known-good row after schema migrations."],"exampleFix":"// before\nassertValidEntity('session', row, 'import');\n// -> Invalid session (import): /harness must be equal to one of the allowed values\n\n// after\nconst { validateEntity } = require('scripts/lib/state-store/schema');\nconst result = validateEntity('session', row);\nif (!result.valid) {\n  log.warn('skipping invalid session', result.errors);\n  continue;\n}\nassertValidEntity('session', row, 'import');","handlingStrategy":"validation","validationCode":"const { validateEntity } = require('scripts/lib/state-store/schema');\n\nfunction writeIfValid(entityName, payload, label) {\n  const { valid, errors } = validateEntity(entityName, payload);\n  if (!valid) {\n    log.warn({ entityName, label, errors }, 'skipping invalid entity');\n    return null;\n  }\n  return payload;\n}\n\nconst clean = writeIfValid('session', row, 'import');\nif (clean) persistSession(clean);","typeGuard":"const { validateEntity } = require('scripts/lib/state-store/schema');\n\nfunction isValidEntity(entityName, payload) {\n  return validateEntity(entityName, payload).valid;\n}","tryCatchPattern":"try {\n  assertValidEntity(entityName, payload, label);\n} catch (error) {\n  if (new RegExp(`^Invalid ${entityName}`).test(error.message)) {\n    // route the row to a dead-letter queue for inspection\n    deadLetterQueue.push({ entityName, payload, error: error.message });\n    return;\n  }\n  throw error;\n}","preventionTips":["Prefer the non-throwing validateEntity at ingest boundaries; reserve assertValidEntity for invariants.","After every schema migration, regenerate fixtures from a known-good row.","Log AJV errors verbatim — they pin the exact field via instancePath.","Add a CI step that validates a representative corpus of payloads against the schema."],"tags":["state-store","schema","ajv","validation","data-quality"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}