{"record":{"id":"eab1914c746ca992","repo":"aeron-io/aeron","slug":"failed-to-send-list-recordings-request","errorCode":null,"errorMessage":"failed to send list recordings request","messagePattern":"failed to send list recordings request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":1408,"sourceCode":"     * @param recordCount     to limit for each query.\n     * @param consumer        to which the descriptors are dispatched.\n     * @return the number of descriptors found and consumed.\n     */\n    public int listRecordings(\n        final long fromRecordingId, final int recordCount, final RecordingDescriptorConsumer consumer)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            isInCallback = true;\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.listRecordings(fromRecordingId, recordCount, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send list recordings request\");\n            }\n\n            return pollForDescriptors(lastCorrelationId, recordCount, consumer);\n        }\n        finally\n        {\n            isInCallback = false;\n            lock.unlock();\n        }\n    }\n\n    /**\n     * List recording descriptors from a recording id with a limit of record count for a given channelFragment and\n     * stream id.\n     * <p>\n     * If the recording id is greater than the largest known id then nothing is returned.\n     *\n     * @param fromRecordingId at which to begin the listing.","sourceCodeStart":1390,"sourceCodeEnd":1426,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L1390-L1426","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check archive availability and control-channel configuration (endpoint, aeron.dir) on both sides.","Retry listRecordings after a short delay; the offer failure is often transient back-pressure.","Re-establish the archive session via AeronArchive.connect() if the control session was closed by the archive.","Throttle catalog-listing calls so the control publication does not back up.","Inspect the control response listener / archive logs for the session-closed or back-pressure signal that preceded the failure."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure the control channel is connected before listing\nif (!archive.archiveProxy().controlPublication().isConnected()) {\n    throw new IllegalStateException(\"archive control publication not connected\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.listRecordings(fromRecordingId, count, consumer);\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"failed to send list recordings request\")) {\n        Thread.sleep(backoffMs); // optionally reconnect, then retry\n    } else { throw e; }\n}","preventionTips":["Verify the archive is running before issuing catalog queries.","Retry listing calls with backoff rather than failing fast on a single rejected offer.","Cache catalog results instead of repeatedly querying the control stream.","Watch control-session liveness and reconnect proactively on session timeout."],"tags":["aeron-archive","backpressure","control-channel","catalog"],"backgroundTag":"api-request-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}