{"record":{"id":"d89e379b0cf4f684","repo":"aeron-io/aeron","slug":"archive-response-for-correlationid-correlationid-error","errorCode":null,"errorMessage":"archive response for correlationId=<correlationId>, error: <errorMessage>","messagePattern":"archive response for correlationId=<correlationId>, error: <errorMessage>","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java","lineNumber":604,"sourceCode":"            (nowMs > (timeOfLastScheduledArchivePollMs + ARCHIVE_POLL_INTERVAL_MS)))\n        {\n            timeOfLastScheduledArchivePollMs = nowMs;\n            pollForResponse(archive, NULL_VALUE);\n        }\n    }\n\n    private static boolean pollForResponse(final AeronArchive archive, final long correlationId)\n    {\n        final ControlResponsePoller poller = archive.controlResponsePoller();\n\n        final int pollCount = poller.poll();\n        if (poller.isPollComplete())\n        {\n            if (poller.controlSessionId() == archive.controlSessionId())\n            {\n                if (poller.code() == ControlResponseCode.ERROR)\n                {\n                    throw new ArchiveException(\"archive response for correlationId=\" + poller.correlationId() +\n                        \", error: \" + poller.errorMessage(),\n                        (int)poller.relevantId(),\n                        poller.correlationId());\n                }\n\n                return poller.correlationId() == correlationId;\n            }\n        }\n        else if (pollCount == 0 && !poller.subscription().isConnected())\n        {\n            throw new ArchiveException(\"archive is not connected\");\n        }\n\n        return false;\n    }\n\n    private static long polledRelevantId(final AeronArchive archive)\n    {","sourceCodeStart":586,"sourceCodeEnd":622,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java#L586-L622","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded errorMessage and error code to identify the archive-side failure","Verify the recordingId exists via listRecordings before merging","Ensure the archive has capacity for additional replay sessions","Check archive logs corresponding to the correlationId"],"exampleFix":"// before: unguarded\nmerge.doWork();\n// after\ntry { merge.doWork(); } catch (ArchiveException e) { log.error(\"archive rejected corrId=\" + e.correlationId() + \": \" + e.getMessage()); }","handlingStrategy":"try-catch","validationCode":"// verify the recording exists before requesting a replay merge\nCounter count = archive.findLastMatchingRecording(minRecordingId, channelFragment, streamId, sessionId);\nif (count.get() == Aeron.NULL_VALUE) throw new IllegalStateException(\"no recording to merge\");","typeGuard":null,"tryCatchPattern":"try { merge.doWork(); }\ncatch (ArchiveException e) { if (e.getMessage().startsWith(\"archive response for correlationId=\")) { handleArchiveError(e.errorCode(), e.getMessage()); } }","preventionTips":["Confirm recordingId validity via listRecordings before merging","Monitor archive capacity and replay session limits","Include correlationId in logs to correlate with archive-side logs"],"tags":["archive","control-response","error-response","replay-merge"],"backgroundTag":"api-error-response","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}