aeron-io/aeron · error · ArchiveException

failed to send replay token request

Error message

failed to send replay token request

What it means

Thrown by AeronArchive.startReplay when the client cannot offer a replay-token request on the archive control publication. The replay token lets the replay be authorized on a separate (response) channel; without successfully sending the request no token is issued. The offer failed because the control publication is CLOSED or NOT_CONNECTED.

Solutions

1. Re-establish the AeronArchive session (reconnect) and retry startReplay
2. Verify the control request channel/stream match the running archive
3. Check archive availability and logs at the time of the call
4. Inspect the Aeron driver error log (aeron.error.log) for publication closure reasons

Example fix

// before
archive.startReplay(recordingId, channel, streamId, replayParams); // throws
// after
try {
    archive.startReplay(recordingId, channel, streamId, replayParams);
} catch (ArchiveException e) {
    archive.close();
    archive = AeronArchive.connect(ctx);
    archive.startReplay(recordingId, channel, streamId, replayParams);
}

// ensure archive session still valid
if (archive == null || archive.isClosed()) archive = AeronArchive.connect(ctx);

try { archive.startReplay(recordingId, ch, sid, params); } catch (ArchiveException e) { reconnectArchive(); }

When it happens

Trigger: Calling startReplay with ReplayParams while the control request publication is closed or no longer connected to the archive (archive down, session invalid, channel misconfigured).

Common situations: Archive restarted between connect and replay; control channel misconfigured; long-lived AeronArchive whose control session's publication was closed by timeout; network drop during replay setup.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• failed to offer async replay response
• failed to send keep alive after archive connect
• timed out wait for replay publication to connect
• when using startReplay with a response channel…
• timed out waiting for replay connection to have available…

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/8a32602e876ddae8. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:4241

                    resultException = ex;
                }
            }
        }

        return resultException;
    }

    private Subscription replayViaResponseChannel(
        final long recordingId,
        final String replayChannel,
        final int replayStreamId,
        final ReplayParams replayParams)
    {
        lastCorrelationId = aeron.nextCorrelationId();

        if (!archiveProxy.requestReplayToken(lastCorrelationId, controlSessionId, recordingId))
        {
            throw new ArchiveException("failed to send replay token request");
        }

        final long replayToken = pollForResponse(lastCorrelationId);

        replayParams.replayToken(replayToken);
        final Subscription replaySubscription = aeron.addSubscription(replayChannel, replayStreamId);
        final ChannelUriStringBuilder uriBuilder = new ChannelUriStringBuilder(context.controlRequestChannel())
            .sessionId((Integer)null)
            .responseCorrelationId(replaySubscription.registrationId())
            .termId((Integer)null).initialTermId((Integer)null).termOffset((Integer)null)
            .termLength(64 * 1024)
            .spiesSimulateConnection(false);

        final String channel = uriBuilder.build();

        try (ExclusivePublication publication =
            aeron.addExclusivePublication(channel, context().controlRequestStreamId()))
        {

View on GitHub (pinned to 6d60124e15)