{"record":{"id":"a3da732f17ea6224","repo":"aeron-io/aeron","slug":"archive-connect-timeout-step-publication-subscription","errorCode":null,"errorMessage":"Archive connect timeout: step= publication= subscription=","messagePattern":"Archive connect timeout: step= publication= subscription=","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":3978,"sourceCode":"                case AWAIT_CHALLENGE_RESPONSE:\n                    pollForResponse();\n                    break;\n\n                case DONE:\n                    return aeronArchive;\n\n                default:\n                    break;\n            }\n\n            return null;\n        }\n\n        private void checkDeadline()\n        {\n            if (deadlineNs - ctx.aeron().context().nanoClock().nanoTime() < 0)\n            {\n                throw new TimeoutException(\n                    \"Archive connect timeout: step=\" + state +\n                    \" publication=\" +\n                    (null != archiveProxy ? archiveProxy.publication() : ctx.controlRequestChannel()) +\n                    \" subscription=\" +\n                    (null != controlResponsePoller ? controlResponsePoller.subscription() :\n                        ctx.controlResponseChannel()));\n            }\n\n            if (Thread.currentThread().isInterrupted())\n            {\n                throw new AeronException(\"unexpected interrupt\");\n            }\n        }\n\n        private void awaitSubscription()\n        {\n            final Aeron aeron = ctx.aeron();\n            if (NULL_VALUE == subscriptionRegistrationId)","sourceCodeStart":3960,"sourceCodeEnd":3996,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L3960-L3996","documentation":"During connection establishment the client moves through states (awaiting publication to connect, awaiting the control response subscription image, awaiting responses) with an overall deadline. checkDeadline() compares the deadline against the Aeron context nanoClock and throws a TimeoutException naming the current step plus the publication/subscription channels involved, so you can see exactly which stage stalled.","triggerScenarios":"step=PUB_CONNECT when the control request publication never gets a connected image (archive not running/unreachable); step=AWAIT_CONTROL_RESPONSE_SUBSCRIPTION or AWAIT_CONTROL_RESPONSE_CONNECTION when the response subscription never establishes or no reply arrives within the timeout.","commonSituations":"Archive process down or wrong control endpoint/port; firewall blocking UDP; controlResponseChannel endpoint not routable from the client host; archive up but on a different cluster/version ignoring requests; very short messageTimeoutNs under load.","solutions":["Verify the archive is running and the controlRequestChannel endpoint matches the archive's control channel.","Check network reachability (ping/telnet/firewall) for both control request and response channels from the client host.","Increase ctx.messageTimeoutNs() (the connect deadline derives from it) if the network is slow but functional.","Ensure the response channel endpoint/port is unique per client and not aliased; check archive logs for received control requests."],"exampleFix":"// before\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(1));\nAeronArchive archive = AeronArchive.connect(ctx);\n// after\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5));\nctx.controlRequestChannel(\"aeron:udp?endpoint=archive-host:8010\");\nctx.controlResponseChannel(\"aeron:udp?endpoint=client-host:8020|alias=client\");\nAeronArchive archive = AeronArchive.connect(ctx);","handlingStrategy":"retry","validationCode":"// pre-check reachability of the control endpoint before connect\n// e.g. DNS resolve + (for TCP) socket probe; for UDP verify config ports differ and are in range","typeGuard":null,"tryCatchPattern":"try { archive = AeronArchive.connect(ctx); } catch (TimeoutException e) { log.error(\"archive connect stalled: \" + e.getMessage()); if (attempts++ < 3) { retryWithBackoff(); } else { throw e; } }","preventionTips":["Verify the archive is running and control endpoint/port match before connecting.","Give connect() a generous messageTimeoutNs; scale it with network RTT.","Check archive logs for incoming control requests when timeouts occur.","Ensure control response endpoints are unique per client instance."],"tags":["aeron","archive","timeout","connection"],"backgroundTag":"request-timeout","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"}