aeron-io/aeron · error · ArchiveException

failed to send list recordings request

Error message

failed to send list recordings request

What it means

AeronArchive.listRecordings() throws this ArchiveException when the listRecordings request could not be offered to the archive control-request publication. archiveProxy.listRecordings() returned false because the publication is not connected, is closed, or its send buffer was full for the whole retry window. No descriptor polling occurs and the consumer callback is never invoked.

Solutions

1. Check archive availability and control-channel configuration (endpoint, aeron.dir) on both sides.
2. Retry listRecordings after a short delay; the offer failure is often transient back-pressure.
3. Re-establish the archive session via AeronArchive.connect() if the control session was closed by the archive.
4. Throttle catalog-listing calls so the control publication does not back up.
5. Inspect the control response listener / archive logs for the session-closed or back-pressure signal that preceded the failure.

// ensure the control channel is connected before listing
if (!archive.archiveProxy().controlPublication().isConnected()) {
    throw new IllegalStateException("archive control publication not connected");
}

try {
    archive.listRecordings(fromRecordingId, count, consumer);
} catch (ArchiveException e) {
    if (e.getMessage().contains("failed to send list recordings request")) {
        Thread.sleep(backoffMs); // optionally reconnect, then retry
    } else { throw e; }
}

When it happens

Trigger: Calling listRecordings(fromRecordingId, recordCount, consumer) when the archive is down, the control session has expired/closed, the control publication's buffer is saturated with earlier unsent commands, or the control channel is misconfigured.

Common situations: Browsing the catalog while the archive process is restarting; long-running clients whose control session timed out; flooding the control stream with listing calls until back-pressure exceeds the proxy's retry budget.

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 recording 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/eab1914c746ca992. Report an issue: GitHub.

Appendix: source

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

     * @param recordCount     to limit for each query.
     * @param consumer        to which the descriptors are dispatched.
     * @return the number of descriptors found and consumed.
     */
    public int listRecordings(
        final long fromRecordingId, final int recordCount, final RecordingDescriptorConsumer consumer)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            isInCallback = true;
            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.listRecordings(fromRecordingId, recordCount, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send list recordings request");
            }

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

    /**
     * List recording descriptors from a recording id with a limit of record count for a given channelFragment and
     * stream id.
     * <p>
     * If the recording id is greater than the largest known id then nothing is returned.
     *
     * @param fromRecordingId at which to begin the listing.

View on GitHub (pinned to 6d60124e15)