ironflow dead-letters
ironflow dead-letters list lists stored dead-letter rows, newest first. Automatic capture retains scoped routing and resume failures, projection decoding and SQL apply failures, and best-effort system event publish failures. Raw application bytes are omitted. JetStream advisories are logging only; transactional outbox failures use their separate table. An empty result does not rule out routing, projection, or publishing failures. It requires events:subscribe and an explicit --env or IRONFLOW_ENV. The value current selects the API key’s environment.
ironflow dead-letters list --env currentironflow dead-letters list --env env_acme_prod --source projection --limit 25 --offset 0 --json| Flag | Default | Description |
|---|---|---|
--env | IRONFLOW_ENV | Environment ID or current; required |
--source | none | Exact source filter |
--limit | 50 | Maximum rows, 1 through 500 |
--offset | 0 | Row offset, 0 through 10000 |
--json | false | Full response with payloads and filtered total count |
--server, -s | IRONFLOW_SERVER_URL or http://localhost:9123 | Server URL |
The table shows ID, source, subject, attempts, creation time, and error. An error longer than 60 characters is cut with .... Control characters are escaped for terminal display. JSON output preserves the complete REST response. Its payload field contains base64 of the stored bytes, including malformed JSON or binary content where the store retains it. Payloads and errors can contain application secrets.
See Dead letters for the response and errors. Transactional outbox dead letters use ironflow outbox dlq.
Automatic records use fixed diagnostic strings and omit payloads, raw subjects, headers and exception text. Broker identities are hashed and include stream, consumer, sequence and timestamp. Duplicate deliveries preserve the first retained record. Capture retries three SQL writes; consumer redelivery retries again if SQL stays unavailable. SQL projection capture and cursor advancement share one transaction.
System event publishing remains best effort. Capture gets three attempts within two seconds, including asynchronous acknowledgement failures. A simultaneous SQL outage can prevent retention. Missing, deleted or ambiguous routing scopes are logged and terminated without capture. Database scope lookup failures and unreadable broker metadata remain retryable without a guessed tenant or identity. SDK projection handler errors, returned HTTP publish errors, control notifications with database reconciliation, output inflation failures, and guard drops keep their existing diagnostics.
The overview dlq_count is the number of retained rows in the selected environment. Retention can prune rows. Zero does not prove that no failure occurred. JetStream maximum-delivery advisories have no durable capture subscription and remain logging only. The transactional outbox has separate listing and counts.