{"record":{"id":"368e4618445ea954","repo":"aeron-io/aeron","slug":"response-for-correlationid-correlationid-error-errormessage","errorCode":null,"errorMessage":"response for correlationId=<correlationId>, error: <errorMessage>","messagePattern":"response for correlationId=<correlationId>, error: <errorMessage>","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2477,"sourceCode":"\n            if (poller.controlSessionId() != controlSessionId)\n            {\n                context.runInvokers();\n                continue;\n            }\n\n            final ControlResponseCode code = poller.code();\n            if (ControlResponseCode.ERROR == code)\n            {\n                final long relevantId = poller.relevantId();\n                if (poller.correlationId() == correlationId)\n                {\n                    if (relevantId == allowedErrorCode)\n                    {\n                        return false;\n                    }\n\n                    throw new ArchiveException(\n                        \"response for correlationId=\" + correlationId + \", error: \" + poller.errorMessage(),\n                        (int)relevantId,\n                        poller.correlationId());\n                }\n                else if (context.errorHandler() != null)\n                {\n                    context.errorHandler().onError(new ArchiveException(\n                        \"response for correlationId=\" + correlationId + \", error: \" + poller.errorMessage(),\n                        (int)relevantId,\n                        poller.correlationId()));\n                }\n            }\n            else if (poller.correlationId() == correlationId)\n            {\n                if (ControlResponseCode.OK != code)\n                {\n                    throw new ArchiveException(\"unexpected response code: \" + code);\n                }","sourceCodeStart":2459,"sourceCodeEnd":2495,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2459-L2495","documentation":"ArchiveException raised when the archive replies with an ERROR control response for the awaited correlationId and the error code is not the single allowedErrorCode the caller tolerates. The message embeds the poller's errorMessage from the archive and the exception carries the archive error code and correlationId.","triggerScenarios":"Calling pollForResponse(invokerType, correlationId, allowedErrorCode) style awaits (e.g. truncate/purge allowing NULL_SESSION) when the archive returns any other error code, such as UNKNOWN_RECORDING, GENERIC, or ACTIVE_LISTING.","commonSituations":"Deleting or truncating a recording that no longer exists; concurrent archive operations on the same recording; catalog errors on the archive; a session invalidated between requests.","solutions":["Read e.errorCode() and the embedded archive errorMessage to identify the archive-side failure.","Check that the target recordingId exists and is not concurrently locked by another archive operation.","If the error code is expected in your workflow, catch it explicitly and treat it as success (as the allowedErrorCode mechanism does).","Re-establish the archive session if the error indicates an invalid or expired control session."],"exampleFix":"// before\narchive.purgeSegments(recordingId, newStartPosition);\n// after\ntry {\n    archive.purgeSegments(recordingId, newStartPosition);\n} catch (ArchiveException e) {\n    if (e.errorCode() == ArchiveException.UNKNOWN_RECORDING) {\n        return; // already gone - treat as success\n    }\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// confirm recording exists and no concurrent operation is in flight\nlong count = archive.getStopPosition(recordingId); // surfaces UNKNOWN_RECORDING early","typeGuard":null,"tryCatchPattern":"try {\n    archive.truncateRecording(recordingId, position);\n} catch (ArchiveException e) {\n    if (e.errorCode() == ArchiveException.UNKNOWN_RECORDING) { /* already deleted */ }\n    else if (e.errorCode() == ArchiveException.ACTIVE_LISTING) { /* retry later */ }\n    else throw e;\n}","preventionTips":["Check recording existence before destructive operations.","Serialize archive mutations per recording to avoid concurrent-operation errors.","Match expected error codes via the allowedErrorCode mechanism rather than ad-hoc catches."],"tags":["aeron-archive","control-response","server-error"],"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"}