Dynamic dead-lettering

After fixing a handler bug, you may need to retry just the messages it failed to process. Track the durable error log and use @Trigger to recover the original request. This provides a selective dead-letter recovery flow.

Here’s how:

1. Deploy a special consumer that tracks the error log.
2. Use @Trigger to access and inspect failed messages.
3. Filter and replay failures based on time, payload type, or originating app.

Example: retrying failed commands

Let’s assume a bug caused command processing to fail in September 2025. The following setup reprocesses those failed commands:

Java

@Consumer(name = "command-dlq",
        minIndex = 115126095052800000L,
        maxIndexExclusive = 115295964364800000L) // 2025-09-01 to 2025-10-01
class CommandReplayHandler {

    @HandleError
    void retry(ConsoleError error, @Trigger(messageType = MessageType.COMMAND) MyCommand failedCommand) {
        Fluxzero.sendCommand(failedCommand);
    }
}

Kotlin

@Consumer(
    name = "command-dlq",
    minIndex = 115126095052800000L,
    maxIndexExclusive = 115295964364800000L // 2025-09-01 to 2025-10-01
)
class CommandReplayHandler {

    @HandleError
    fun retry(error: ConsoleError, @Trigger(messageType = MessageType.COMMAND) failedCommand: MyCommand) {
        Fluxzero.sendCommand(failedCommand)
    }
}

Caution

Run recovery after fixing the cause. Restrict it to the affected command type and time window, and make sure retrying cannot duplicate external effects that already succeeded. A failed handler may have completed part of its work.

Tip

The original MyCommand payload is restored and retried transparently. You can combine this with logic that deduplicates, transforms, or selectively suppresses retries.

When to use the Error log

Use case	How the Error log helps
Fix a bug retroactively	Replay failed commands from the past
Validate new handler logic	Test it against real-world errors
Retry transient failures	Re-issue requests with retry logic
Clean up or suppress errors	Filter out known false-positives

The error log acts as a time-travel debugger — it gives you full control over how and when to address failures, now or in the future.

---

Routing with @RoutingKey

Retrying publishes the command again, so its normal routing rules apply. Routing controls which tracker processes related messages inside a consumer; it does not make retries idempotent. See custom routing keys.

Payload fields or class-level @RoutingKey select a key from the message. A handler-level override requires ignoreSegment = true on its consumer. The tracking guide and RoutingKey API describe these choices.