aeron-io/aeron · error · ArchiveException

timed out wait for replay publication to connect

Error message

timed out wait for replay publication to connect

What it means

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.

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)

Example fix

// before
ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5)); // too short
// after
ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(30));

Defensive patterns

Strategy: retry

Validate before calling

// precheck replay channel reachability
if (!aeron.countersReader().hasSubscription(replayChannel, replayStreamId)) {
    // subscriber not in place; add it before starting replay
}

Try / catch

try { archive.startReplay(...); } catch (ArchiveException e) { if (msg.contains("timed out")) increaseTimeoutAndRetry(); }

Prevention

Set messageTimeoutNs comfortably above worst-case setup time
Ensure the replay subscription exists before startReplay
Verify replay channel network path (endpoints, firewall)

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/f401cb64f8d57a0b. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:4270

            .termLength(64 * 1024)
            .spiesSimulateConnection(false);

        final String channel = uriBuilder.build();

        try (ExclusivePublication publication =
            aeron.addExclusivePublication(channel, context().controlRequestStreamId()))
        {
            final ArchiveProxy responseArchiveProxy = new ArchiveProxy(publication);

            final int pubLmtCounterId = aeron.countersReader().findByTypeIdAndRegistrationId(
                AeronCounters.DRIVER_PUBLISHER_LIMIT_TYPE_ID, publication.registrationId());

            final long deadlineNs = aeron.context().nanoClock().nanoTime() + context.messageTimeoutNs();
            while (!publication.isConnected() || 0 == aeron.countersReader().getCounterValue(pubLmtCounterId))
            {
                if (deadlineNs <= aeron.context().nanoClock().nanoTime())
                {
                    throw new ArchiveException("timed out wait for replay publication to connect");
                }

                idleStrategy.idle();
            }

            if (!responseArchiveProxy.replay(
                recordingId, replayChannel, replayStreamId, replayParams, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send replay request");
            }

            pollForResponse(lastCorrelationId);
            while (!replaySubscription.isConnected())
            {
                idleStrategy.idle();
            }

            return replaySubscription;

View on GitHub (pinned to 6d60124e15)