aeron-io/aeron · error · TimeoutException

- correlationId= messageTimeout=

Error message

<errorMessage> - correlationId=<correlationId> messageTimeout=<formattedDuration>

What it means

TimeoutException built by checkDeadline when polling for an archive control response exceeds messageTimeoutNs. The client sent the request but no matching response arrived before the deadline; the message includes the correlationId, the configured timeout, and an errorMessage describing which operation timed out.

Solutions

1. Increase messageTimeout in AeronArchive.Context (e.g. ctx.messageTimeout(TimeUnit.SECONDS.toNanos(30))).
2. Verify the control response channel/streamId match the archive's configured response endpoint.
3. Check archive logs/health for the correlationId to see if the request was processed.
4. Retry the operation on a new archive session if the archive was restarted mid-request.

Example fix

// before
AeronArchive.connect(new AeronArchive.Context());
// after
AeronArchive.connect(new AeronArchive.Context()
    .messageTimeout(TimeUnit.SECONDS.toNanos(30)));

try {
    archive.listRecording(recordingId);
} catch (TimeoutException e) {
    // retry with larger timeout or check archive health
    ctx.messageTimeout(TimeUnit.SECONDS.toNanos(60));
}

When it happens

Trigger: Any request/response call (startReplay, listRecordings, truncate, etc.) where pollForResponse exhausts ctx.messageTimeoutNs() waiting for the archive's reply on the control response channel.

Common situations: Archive overloaded or stuck (e.g. slow catalog, disk issues); request never delivered due to backpressure; control response subscription connected to the wrong stream; very long-running listRecordings over huge catalogs exceeding the default timeout.

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

• failed get acknowledgement of replay request to: " +…
• failed get replay image for sessionId=" +…
• failed to send replay request
• timed out wait for replay publication to connect
• timed out waiting for replay connection to have available…

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

Appendix: source

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

            if (!archiveProxy.updateChannel(recordingId, newChannel, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send update channel request");
            }

            pollForResponse(lastCorrelationId);
        }
        finally
        {
            lock.unlock();
        }
    }

    private void checkDeadline(final long deadlineNs, final String errorMessage, final long correlationId)
    {
        if (deadlineNs - nanoClock.nanoTime() < 0)
        {
            throw new TimeoutException(
                errorMessage + " - correlationId=" + correlationId + " messageTimeout=" +
                SystemUtil.formatDuration(messageTimeoutNs));
        }

        if (Thread.currentThread().isInterrupted())
        {
            throw new AeronException("unexpected interrupt");
        }
    }

    private void pollNextResponse(final long correlationId, final long deadlineNs, final ControlResponsePoller poller)
    {
        idleStrategy.reset();

        while (true)
        {
            final int fragments = poller.poll();

View on GitHub (pinned to 6d60124e15)