aeron-io/aeron · error · ArchiveException

archive response for correlationId=

Error message

archive response for correlationId=<correlationId>, error: <errorMessage>

What it means

ReplayMerge.pollForResponse processes a control response from the archive; when the poller reports an ERROR response code, the merge rethrows it as an ArchiveException carrying the correlationId, the archive's error message, and the error code as relevantId. This surfaces server-side archive failures (e.g. unknown recording, session rejected) to the caller.

Solutions

1. Read the embedded errorMessage and error code to identify the archive-side failure
2. Verify the recordingId exists via listRecordings before merging
3. Ensure the archive has capacity for additional replay sessions
4. Check archive logs corresponding to the correlationId

Example fix

// before: unguarded
merge.doWork();
// after
try { merge.doWork(); } catch (ArchiveException e) { log.error("archive rejected corrId=" + e.correlationId() + ": " + e.getMessage()); }

// verify the recording exists before requesting a replay merge
Counter count = archive.findLastMatchingRecording(minRecordingId, channelFragment, streamId, sessionId);
if (count.get() == Aeron.NULL_VALUE) throw new IllegalStateException("no recording to merge");

try { merge.doWork(); }
catch (ArchiveException e) { if (e.getMessage().startsWith("archive response for correlationId=")) { handleArchiveError(e.errorCode(), e.getMessage()); } }

When it happens

Trigger: Any archive request issued during the merge — getRecordingPosition, startReplay (replay), attemptLiveJoin, or the poll in checkProgress — returns a ControlResponse with code=ERROR from the archive's control session.

Common situations: Requesting a recordingId that does not exist or was purged; archive rejected replay due to exhausted replay sessions; permission or session errors on the archive.

Related errors

• unexpected response: code=
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set
• AeronArchive.Context.controlResponseChannel must be set

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java:604

            (nowMs > (timeOfLastScheduledArchivePollMs + ARCHIVE_POLL_INTERVAL_MS)))
        {
            timeOfLastScheduledArchivePollMs = nowMs;
            pollForResponse(archive, NULL_VALUE);
        }
    }

    private static boolean pollForResponse(final AeronArchive archive, final long correlationId)
    {
        final ControlResponsePoller poller = archive.controlResponsePoller();

        final int pollCount = poller.poll();
        if (poller.isPollComplete())
        {
            if (poller.controlSessionId() == archive.controlSessionId())
            {
                if (poller.code() == ControlResponseCode.ERROR)
                {
                    throw new ArchiveException("archive response for correlationId=" + poller.correlationId() +
                        ", error: " + poller.errorMessage(),
                        (int)poller.relevantId(),
                        poller.correlationId());
                }

                return poller.correlationId() == correlationId;
            }
        }
        else if (pollCount == 0 && !poller.subscription().isConnected())
        {
            throw new ArchiveException("archive is not connected");
        }

        return false;
    }

    private static long polledRelevantId(final AeronArchive archive)
    {

View on GitHub (pinned to 6d60124e15)