thedotmack/claude-mem · error · ServerGenerationJobPayloadValidationError

ServerGenerationJobPayloadValidationError

Error message

ServerGenerationJobPayloadValidationError

What it means

assertServerGenerationJobPayload validates an unknown payload against ServerGenerationJobPayloadSchema (Zod). If parsing fails it throws ServerGenerationJobPayloadValidationError carrying the Zod issues, because processing a malformed generation job would produce corrupt or unsafe behavior downstream.

Solutions

1. Fix the producer so it enqueues payloads matching ServerGenerationJobPayloadSchema
2. Read the Zod issues on the error to identify the exact missing/mismatched fields
3. Drain or migrate stale jobs created under the old schema before deploying the new one
4. If extending the schema, make new fields optional or versioned to stay backward-compatible

Example fix

// before
await queue.add(jobId, { prompt }); // missing required 'generationId'
// after
await queue.add(jobId, { prompt, generationId: crypto.randomUUID() });

const parsed = ServerGenerationJobPayloadSchema.safeParse(candidate);
if (!parsed.success) {
  console.error(parsed.error.issues);
  throw new Error('payload fails ServerGenerationJobPayloadSchema');
}

const isValidPayload = (c: unknown): c is ServerGenerationJobPayload =>
  ServerGenerationJobPayloadSchema.safeParse(c).success;

try {
  const payload = assertServerGenerationJobPayload(candidate);
  // process payload
} catch (e) {
  if (e instanceof ServerGenerationJobPayloadValidationError) {
    logger.error('invalid job payload', { issues: e.issues });
    return; // or dead-letter the job
  }
  throw e;
}

When it happens

Trigger: A job dequeued by process() (or passed to validated()) whose payload does not match the schema: missing required fields, wrong types, or unexpected shapes — e.g. jobs enqueued by an older version or hand-crafted entries.

Common situations: Schema updated after jobs were already queued; a different service enqueues payloads that drifted from the current schema; manual Redis inspection/insertion of job records; version skew between producer and consumer.

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

• Invalid transcript watch config
• schema v46: . row is not a positive canonical uint64…
• server job ID must not contain
• sync hub status: response must be an object
• sync hub status: response requires decimal-string…

AI-assisted analysis of thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/a2cab54351ae936c. Report an issue: GitHub.

Appendix: source

Thrown at src/server/jobs/types.ts:124

  constructor(issues: z.ZodIssue[]) {
    super(`invalid server generation job payload: ${issues.map(i => i.message).join('; ')}`);
    this.issues = issues;
  }
}

/**
 * Validate a candidate BullMQ payload against the discriminated union and
 * return a typed payload, or throw `ServerGenerationJobPayloadValidationError`.
 * Use this at every enqueue site so a malformed payload never enters the
 * transport — the worker MUST also re-validate from Postgres but defense in
 * depth is cheap.
 */
export function assertServerGenerationJobPayload(
  candidate: unknown,
): ServerGenerationJobPayload {
  const result = ServerGenerationJobPayloadSchema.safeParse(candidate);
  if (!result.success) {
    throw new ServerGenerationJobPayloadValidationError(result.error.issues);
  }
  return result.data as ServerGenerationJobPayload;
}

View on GitHub (pinned to d8bc9755e7)