Troubleshooting
| Problem | Check or action |
|---|---|
| Empty transaction page | Check next_block and cursor; continue if the cursor is non-null. |
| Invalid range | Compare the request with /height coverage. to_block is exclusive. |
| HTTP 400 | Check field names, duplicate selections, filter syntax and endpoint capabilities. |
HTTP 409 REORG | A chain or physical-layout epoch changed. Discard the old cursor, recheck canonicality and reconcile before restarting. |
| Rate limited | Honor Retry-After and use bounded backoff. |
| Source unavailable | Check /ready and /height; process liveness alone is insufficient. |
catalog segment count / catalog_consolidation_required | Run build-info on the exact writer executable used by the service. Use bounded lossless consolidation; preserve history and existing Chef projects. |
archive_disk_budget_exhausted | Measure all archive files against --max-disk-gib, including retired copies and the 268,435,456-byte append reserve. Physical free disk alone does not prove headroom. Use verified offline reclamation with all archive readers quiesced. |
| Authentication rejected | Verify the intended endpoint and its bearer-token policy. |
| SDK timeout | Check request/stream deadlines and the caller's cancellation signal. |
| Transaction not found | Check the queried range; an archive miss does not imply pending. |
| No memo text in Prep | Use Chef's local memo workflow for authorized notes. |
Keep the HTTP status, error code and public request parameters when debugging. Redact credentials. See the query contract and client options for details.
The offline reclamation guide separates active history from redundant retired files. Unknown, branch and unpublished outputs require classification; they are not automatic deletion targets. Reclamation does not change consumer identity or source timestamps.
The 28 October budget recovery reclaimed 2,152,532,167 bytes of proven copies before an operator-approved increase to a 26 GiB archive allocation. It records fresh source/consumer checks and startup cost; additional capacity is finite and is not an uptime guarantee.
The 27 October catalog recovery report records the 30,000-reference incident and its verification. Follow now publishes new blocks promptly and consolidates bounded historical groups. All replacement records are compared before atomic publication; retired source files remain for old reader snapshots. Compression-only repack does not reduce reference count. The operator command preserves history and performs no RPC; resume follow for genuine fresh readiness rather than editing timestamps.