{"record":{"id":"f7b6467e1c189fac","repo":"aeron-io/aeron","slug":"failed-to-send-list-recording-request","errorCode":null,"errorMessage":"failed to send list recording request","messagePattern":"failed to send list recording request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":1491,"sourceCode":"     *\n     * @param recordingId at which to begin the listing.\n     * @param consumer    to which the descriptors are dispatched.\n     * @return the number of descriptors found and consumed.\n     */\n    public int listRecording(final long recordingId, final RecordingDescriptorConsumer consumer)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n            isInCallback = true;\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.listRecording(recordingId, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send list recording request\");\n            }\n\n            return pollForDescriptors(lastCorrelationId, 1, consumer);\n        }\n        finally\n        {\n            isInCallback = false;\n            lock.unlock();\n        }\n    }\n\n    /**\n     * Get the start position for a recording.\n     *\n     * @param recordingId of the recording for which the position is required.\n     * @return the start position of a recording.\n     * @see #getStopPosition(long)\n     */","sourceCodeStart":1473,"sourceCodeEnd":1509,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L1473-L1509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the archive process is up and the control channel endpoint/ports are correct.","Retry listRecording after a brief delay; the failure is commonly transient back-pressure.","Reconnect via AeronArchive.connect() if the control session was closed server-side.","Cache recording descriptors client-side instead of repeatedly querying the control stream.","Check archive logs for session timeouts or publication errors preceding the failed offer."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if (!archive.archiveProxy().controlPublication().isConnected()) {\n    throw new IllegalStateException(\"archive control publication not connected\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.listRecording(recordingId, consumer);\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"failed to send list recording request\")) {\n        Thread.sleep(backoffMs); // retry or reconnect\n    } else { throw e; }\n}","preventionTips":["Cache single-recording descriptors to reduce control-stream traffic.","Check publication connectivity before each archive command.","Retry with backoff; do not treat one rejected offer as permanent.","Handle session timeouts by recreating the AeronArchive session."],"tags":["aeron-archive","backpressure","control-channel"],"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"}