BreezyCorp Handbook

Appearance

Notes generation went to NOTES_ERROR ​

The engagement transitioned to NOTES_ERROR after Generate notes. The Notes tab shows a failure record with model id, request id, and an error class.

What this means ​

The single Claude Sonnet call for notes failed. Statements remain valid; only the notes call broke. The engagement is recoverable.

Causes (most common first) ​

  1. Transient API issue. Rate limit, timeout, intermittent 5xx from Anthropic. Most common; retry resolves.
  2. JSON parse failure. The LLM returned a response that doesn't conform to the expected {notes, directors_report} schema. Often a prompt-truncation artefact if the engagement context is unusually large.
  3. Schema mismatch. The LLM returned a note_key that isn't in the taxonomy's note_trigger set, or a block type that isn't paragraph | subheading | table | financial_results_placeholder.
  4. Worker not connected. The generate-notes handler is unregistered or the worker isn't running.

Diagnose ​

Open the Notes tab; read the failure record:

FieldWhat to read
modelShould be claude-sonnet-5
requestIdAnthropic request id — useful for support tickets
errorClassTimeout / RateLimit / JsonParseError / SchemaError
errorMessageFree-form error detail

Worker logs:

bash
docker logs breezycorp-monorepo-worker-1 2>&1 | grep -A 10 "generate-notes" | tail -30

Fix ​

  • Transient (Timeout, RateLimit, 5xx): click Retry on the failure record. The handler transitions NOTES_ERROR → STATEMENTS_GENERATED and re-enqueues. Most failures clear on first retry.
  • JsonParseError: retry once. If it recurs, the prompt is likely landing on an edge case. Reduce the engagement scope (regenerate statements with anomalies cleared; verify disclosures are minimal) and retry.
  • SchemaError: the LLM emitted an unexpected note_key or block type. Retry. If it recurs, file an issue with the failure record attached.
  • Worker not connected: check pnpm dev worker logs; ensure the handler is registered.

When retries don't help ​

After 3 retries on the same engagement, escalate to Senior Accountant. Capture:

  • Engagement id
  • Failure record (model, requestId, errorClass, errorMessage)
  • Worker logs around the failure
  • Any unusual TB or disclosure responses

Internal use only — BreezyCorp