{"record":{"id":"3b3ef2bb59ede951","repo":"aeron-io/aeron","slug":"unexpected-response-code","errorCode":null,"errorMessage":"unexpected response: code=","messagePattern":"unexpected response: code=","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":4158,"sourceCode":"\n                    correlationId = ctx.aeron().nextCorrelationId();\n                    state(State.SEND_CHALLENGE_RESPONSE);\n                }\n                else\n                {\n                    final ControlResponseCode code = controlResponsePoller.code();\n                    if (ControlResponseCode.OK != code)\n                    {\n                        archiveProxy.closeSession(controlSessionId);\n                        if (ControlResponseCode.ERROR == code)\n                        {\n                            final String errorMessage = controlResponsePoller.errorMessage();\n                            final int errorCode = (int)controlResponsePoller.relevantId();\n\n                            throw new ArchiveException(errorMessage, errorCode, correlationId);\n                        }\n\n                        throw new ArchiveException(\n                            \"unexpected response: code=\" + code, correlationId, AeronException.Category.ERROR);\n                    }\n\n                    if (State.AWAIT_ARCHIVE_ID_RESPONSE == state)\n                    {\n                        final long archiveId = controlResponsePoller.relevantId();\n                        aeronArchive = transitionToDone(archiveId);\n                    }\n                    else\n                    {\n                        final int archiveProtocolVersion = controlResponsePoller.version();\n                        if (archiveProtocolVersion < PROTOCOL_VERSION_WITH_ARCHIVE_ID)\n                        {\n                            aeronArchive = transitionToDone(NULL_VALUE);\n                        }\n                        else\n                        {\n                            correlationId = ctx.aeron().nextCorrelationId();","sourceCodeStart":4140,"sourceCodeEnd":4176,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L4140-L4176","documentation":"While awaiting a control response, the client reads the response code from the ControlResponsePoller. If a response with an error/invalid code arrives without a usable errorMessage (so the normal ArchiveException(errorMessage, errorCode) path is skipped), the library throws ArchiveException('unexpected response: code=<code>') tagged as Category.ERROR with the correlationId, indicating an unrecognized archive reply.","triggerScenarios":"The archive (or an intermediary) sends a control response with a code the client does not handle — e.g. a newer archive protocol version introducing a new ControlResponseCode, or a corrupted/mismatched response correlation leading the client to process a foreign message.","commonSituations":"Running a client older than the archive (protocol drift); connecting to the wrong archive that emits different response semantics; custom extensions to the protocol on the archive side.","solutions":["Align client and archive versions — upgrade aeron-archive/aeron-all on both sides so response codes are understood.","Log the numeric code and correlationId from the ArchiveException to identify which message produced the unrecognized reply.","Check for multiple archives on the same control response channel (aliased endpoints) mixing replies into your subscription.","If you extended the protocol, add handling for the new code in the client poller/await loop."],"exampleFix":"// before\n// client built against aeron 1.40 talking to archive 1.44 with new response codes\n// after\n// upgrade the client dependency to match the archive:\n// <dependency><artifactId>aeron-archive</artifactId><version>1.44.1</version></dependency>","handlingStrategy":"try-catch","validationCode":"// check version compatibility at startup\n// compare AeronArchive.Configuration protocol/version info with the archive's via ControlResponsePoller version events","typeGuard":null,"tryCatchPattern":"try { archive.awaitResponse(correlationId); } catch (ArchiveException e) { log.error(\"unexpected archive response code=\" + e.getMessage() + \" corrId=\" + e.correlationId()); }","preventionTips":["Keep aeron-archive client and archive server on the same release train.","Log the numeric response code and correlationId to trace the offending message.","Isolate the control response channel per client so foreign replies cannot mix in.","Avoid protocol extensions unless the client poller is updated to handle the new codes."],"tags":["aeron","archive","control-response","protocol","version-mismatch"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}