affaan-m/ECC · error · Error

Invalid )` : ''}

Error message

Invalid ${entityName}${label ? ` (${label})` : ''}: ${formatValidationErrors(result.errors)}

What it means

assertValidEntity runs the entity's JSON-schema validator and throws with a consolidated list of validation errors if the payload does not conform. The label parameter lets callers annotate which logical record failed. All insert/upsert paths in the state store funnel through this guard.

Solutions

Read the error's formatted validation path list and add/fix the named fields in the payload.
Run validateEntity(entityName, payload) directly to see the full error list before calling the insert/upsert API.
Align the payload to the current schema version - regenerate records from producers that emit the old shape.
Wrap the call in try/catch and log the payload for inspection when validation fails in batch jobs.

Example fix

// before
upsertWorkItem({ id: 'w-1' }); // missing required status
// after
upsertWorkItem({ id: 'w-1', status: 'open', title: 'Fix bug' });

Defensive patterns

Strategy: try-catch

Validate before calling

const result = validateEntity('workItem', payload);
if (!result.valid) console.error(formatValidationErrors(result.errors));

Type guard

const looksValid = (p) => p != null && typeof p === 'object';

Try / catch

try {
  upsertWorkItem(payload);
} catch (e) {
  if (String(e.message).startsWith('Invalid workItem')) {
    console.error('Payload rejected:', JSON.stringify(payload));
  }
  throw e;
}

Prevention

Run validateEntity on payloads before insert/upsert in dev/test.
Keep producers and the schema in the same version window.
Write round-trip tests: insert then read back every entity type.
Log the full formatted validation errors, not just the message head.

When it happens

Trigger: Calling insertDecision/insertGovernanceEvent/insertSkillRun/upsertInstallState/upsertWorkItem/upsertSession with a payload missing required fields, with wrong property types, or violating constraints (e.g. non-ISO dates, empty required strings).

Common situations: Constructing records by hand and forgetting a required column; migrating data from an older schema with different field types; passing null/undefined instead of a full payload object.

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

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

Appendix: source

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

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

function validateEntity(entityName, payload) {
  const validator = getEntityValidator(entityName);
  const valid = validator(payload);
  return {
    valid,
    errors: validator.errors || [],
  };
}

function assertValidEntity(entityName, payload, label) {
  const result = validateEntity(entityName, payload);
  if (!result.valid) {
    throw new Error(`Invalid ${entityName}${label ? ` (${label})` : ''}: ${formatValidationErrors(result.errors)}`);
  }
}

module.exports = {
  assertValidEntity,
  formatValidationErrors,
  readSchema,
  validateEntity,
};

View on GitHub (pinned to 8321021c54)