{"record":{"id":"f401cb64f8d57a0b","repo":"aeron-io/aeron","slug":"timed-out-wait-for-replay-publication-to-connect","errorCode":null,"errorMessage":"timed out wait for replay publication to connect","messagePattern":"timed out wait for replay publication to connect","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":4270,"sourceCode":"            .termLength(64 * 1024)\n            .spiesSimulateConnection(false);\n\n        final String channel = uriBuilder.build();\n\n        try (ExclusivePublication publication =\n            aeron.addExclusivePublication(channel, context().controlRequestStreamId()))\n        {\n            final ArchiveProxy responseArchiveProxy = new ArchiveProxy(publication);\n\n            final int pubLmtCounterId = aeron.countersReader().findByTypeIdAndRegistrationId(\n                AeronCounters.DRIVER_PUBLISHER_LIMIT_TYPE_ID, publication.registrationId());\n\n            final long deadlineNs = aeron.context().nanoClock().nanoTime() + context.messageTimeoutNs();\n            while (!publication.isConnected() || 0 == aeron.countersReader().getCounterValue(pubLmtCounterId))\n            {\n                if (deadlineNs <= aeron.context().nanoClock().nanoTime())\n                {\n                    throw new ArchiveException(\"timed out wait for replay publication to connect\");\n                }\n\n                idleStrategy.idle();\n            }\n\n            if (!responseArchiveProxy.replay(\n                recordingId, replayChannel, replayStreamId, replayParams, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send replay request\");\n            }\n\n            pollForResponse(lastCorrelationId);\n            while (!replaySubscription.isConnected())\n            {\n                idleStrategy.idle();\n            }\n\n            return replaySubscription;","sourceCodeStart":4252,"sourceCodeEnd":4288,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L4252-L4288","documentation":"Thrown while awaiting the replay publication created on the response archive to become connected AND its publication limit counter to become non-zero, within context.messageTimeoutNs(). If either the subscriber never connects or the archive never grants available window before the deadline, this error is raised.","triggerScenarios":"startReplay with a response-channel setup: the replay Publication fails to connect (no subscriber on replayChannel) or the archive does not advance the publication limit before messageTimeoutNs elapses.","commonSituations":"Replay channel unreachable from the client (wrong replayChannel/replayStreamId); archive overloaded or replay not started on the server side; messageTimeoutNs too short for large/slow setups; firewall blocking the replay channel.","solutions":["Verify replayChannel and replayStreamId are correct and reachable by the client","Increase AeronArchive.Context.messageTimeoutNs","Confirm the archive actually started the replay (check archive logs for the correlation id)","Check that nothing blocks the replay publication (firewall, wrong endpoints, driver errors)"],"exampleFix":"// before\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5)); // too short\n// after\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(30));","handlingStrategy":"retry","validationCode":"// precheck replay channel reachability\nif (!aeron.countersReader().hasSubscription(replayChannel, replayStreamId)) {\n    // subscriber not in place; add it before starting replay\n}","typeGuard":null,"tryCatchPattern":"try { archive.startReplay(...); } catch (ArchiveException e) { if (msg.contains(\"timed out\")) increaseTimeoutAndRetry(); }","preventionTips":["Set messageTimeoutNs comfortably above worst-case setup time","Ensure the replay subscription exists before startReplay","Verify replay channel network path (endpoints, firewall)"],"tags":["aeron-archive","replay","timeout","publication-connect"],"backgroundTag":"request-timeout","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}