{"record":{"id":"87d2f133e988ae9d","repo":"aeron-io/aeron","slug":"archive-context-archiveclientcontext-controlresponsechannel","errorCode":null,"errorMessage":"Archive.Context.archiveClientContext.controlResponseChannel must be set if Archive.Context.controlChannelEnabled is false","messagePattern":"Archive\\.Context\\.archiveClientContext\\.controlResponseChannel must be set if Archive\\.Context\\.controlChannelEnabled is false","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1545,"sourceCode":"                    if (null == endpoint || -1 == (separatorIndex = endpoint.lastIndexOf(':')))\n                    {\n                        throw new ConfigurationException(\n                            \"Unable to derive Archive.Context.archiveClientContext.controlResponseChannel as \" +\n                                \"Archive.Context.controlChannel.endpoint=\" + endpoint +\n                                \" and is not in the <host>:<port> format\");\n                    }\n\n                    final String responseEndpoint = endpoint.substring(0, separatorIndex) + \":0\";\n                    final String responseChannel = new ChannelUriStringBuilder()\n                        .media(\"udp\")\n                        .endpoint(responseEndpoint)\n                        .build();\n\n                    archiveClientContext.controlResponseChannel(responseChannel);\n                }\n                else\n                {\n                    throw new ConfigurationException(\n                        \"Archive.Context.archiveClientContext.controlResponseChannel must be set if \" +\n                            \"Archive.Context.controlChannelEnabled is false\"\n                    );\n                }\n            }\n\n            archiveClientContext\n                .aeron(aeron)\n                .lock(NoOpLock.INSTANCE)\n                .errorHandler(errorHandler)\n                .clientName(clientName);\n\n            if (null == controlSessionsCounter)\n            {\n                controlSessionsCounter = ArchiveCounters.allocate(\n                    aeron, tempBuffer, ARCHIVE_CONTROL_SESSIONS_TYPE_ID, \"Archive Control Sessions\", archiveId);\n            }\n            validateCounterTypeId(aeron, controlSessionsCounter, ARCHIVE_CONTROL_SESSIONS_TYPE_ID);","sourceCodeStart":1527,"sourceCodeEnd":1563,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1527-L1563","documentation":"When the archive control channel is disabled (controlChannelEnabled=false), Archive still needs a control-response channel for its internal archive client, which it can no longer derive. If Archive.Context.archiveClientContext.controlResponseChannel is not set in that case, Archive throws ConfigurationException.","triggerScenarios":"Launching Archive with .controlChannelEnabled(false) and no controlResponseChannel configured on the archiveClientContext.","commonSituations":"Disabling the external control request/response channels for a recording-only archive but forgetting that the internal client still needs a response channel setting.","solutions":["Set archiveClientContext.controlResponseChannel(\"aeron:udp?endpoint=<host>:0\") (or an appropriate local channel) when disabling the control channel.","If a control channel is actually required, leave controlChannelEnabled(true) and configure it.","Review Archive.Configuration defaults for the control response channel and set it explicitly in embedded deployments."],"exampleFix":"// before\nctx.controlChannelEnabled(false);\n// after\nctx.controlChannelEnabled(false)\n   .archiveClientContext(new Aeron.Context()\n       .controlResponseChannel(\"aeron:udp?endpoint=localhost:0\"));","handlingStrategy":"validation","validationCode":"if (!controlChannelEnabled && archiveClientContext.controlResponseChannel() == null)\n{\n    throw new IllegalArgumentException(\"controlResponseChannel required when controlChannelEnabled=false\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair every controlChannelEnabled(false) with an explicit archiveClientContext.controlResponseChannel","Document embedded-archive configuration invariants in deployment scripts"],"tags":["aeron","archive","configuration"],"backgroundTag":"missing-required-config-field","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"}