aeron-io/aeron · error · ArchiveException

timed out waiting for replay connection to have available…

Error message

timed out waiting for replay connection to have available publication limit

What it means

Generic deadline check helper: thrown when a wait deadline (deadlineNs) has passed while polling for a condition, here reported as 'replay connection to have available publication limit'. The replay publication connected but the archive never raised the publication limit (available window) before the timeout.

Solutions

Increase messageTimeoutNs in AeronArchive.Context
Confirm the archive actually started the replay (correlation id in archive logs)
Check subscriber/consumer progress — the limit stays 0 while the replay subscription is not draining
Verify no driver errors and sufficient network capacity between archive and client

Example fix

// before
ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5));
// after
ctx.messageTimeoutNs(TimeUnit.MINUTES.toNanos(1));

Defensive patterns

Strategy: retry

Validate before calling

// ensure timeout is adequate
if (ctx.messageTimeoutNs() < TimeUnit.SECONDS.toNanos(30)) { ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(30)); }

Try / catch

try { archive.startReplay(...); } catch (ArchiveException e) { if (e.getMessage().contains("timed out")) { raiseTimeout(); retry(); } }

Prevention

Size messageTimeoutNs for slow archives and networks
Ensure the replay subscription is actively draining
Check archive load and publication limit progression via counters

When it happens

Trigger: startReplay response-channel flow waits for pubLmtCounterId > 0 with checkDeadline(deadlineNs, ...); the archive does not grant publication window within context.messageTimeoutNs.

Common situations: Archive slow or overloaded; replay subscription-side backpressure; messageTimeoutNs too small; archive failed to start the replay so the limit never advances.

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/414b3e2037723df0. Report an issue: GitHub.

Appendix: source

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

            {
                throw new ArchiveException("failed to send replay request");
            }

            pollForResponse(lastCorrelationId);

            return lastCorrelationId;
        }
    }

    private static void checkDeadline(
        final IdleStrategy idleStrategy,
        final NanoClock nanoClock,
        final long deadlineNs,
        final String msg)
    {
        if (deadlineNs <= nanoClock.nanoTime())
        {
            throw new ArchiveException(msg);
        }

        idleStrategy.idle();
    }
}

View on GitHub (pinned to 6d60124e15)