aeron-io/aeron · error · ArchiveException

failed to send list recording request

Error message

failed to send list recording request

What it means

AeronArchive.listRecording() throws this ArchiveException when the single-recording descriptor request could not be offered to the archive control-request publication. archiveProxy.listRecording() returned false (publication not connected, closed, or buffer full for the retry window), so pollForDescriptors is never reached and no RecordingDescriptor is delivered to the consumer.

Solutions

1. Confirm the archive process is up and the control channel endpoint/ports are correct.
2. Retry listRecording after a brief delay; the failure is commonly transient back-pressure.
3. Reconnect via AeronArchive.connect() if the control session was closed server-side.
4. Cache recording descriptors client-side instead of repeatedly querying the control stream.
5. Check archive logs for session timeouts or publication errors preceding the failed offer.

if (!archive.archiveProxy().controlPublication().isConnected()) {
    throw new IllegalStateException("archive control publication not connected");
}

try {
    archive.listRecording(recordingId, consumer);
} catch (ArchiveException e) {
    if (e.getMessage().contains("failed to send list recording request")) {
        Thread.sleep(backoffMs); // retry or reconnect
    } else { throw e; }
}

When it happens

Trigger: Calling listRecording(recordingId, consumer) when the archive control publication cannot accept the message: archive down, control session expired/closed, control-request buffer back-pressured, or misconfigured control channel.

Common situations: Looking up one recording's details right after the archive restarted; stale long-lived archive clients whose session the archive has reaped; bursts of per-recording lookups overloading the control stream.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• failed to send list recordings request
• failed to send get start position request
• failed to send get recording position request
• failed to send get stop position request
• failed to send get max recorded position request

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

Appendix: source

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

     *
     * @param recordingId at which to begin the listing.
     * @param consumer    to which the descriptors are dispatched.
     * @return the number of descriptors found and consumed.
     */
    public int listRecording(final long recordingId, final RecordingDescriptorConsumer consumer)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();
            isInCallback = true;

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.listRecording(recordingId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send list recording request");
            }

            return pollForDescriptors(lastCorrelationId, 1, consumer);
        }
        finally
        {
            isInCallback = false;
            lock.unlock();
        }
    }

    /**
     * Get the start position for a recording.
     *
     * @param recordingId of the recording for which the position is required.
     * @return the start position of a recording.
     * @see #getStopPosition(long)
     */

View on GitHub (pinned to 6d60124e15)