aeron-io/aeron · error · ArchiveException

failed to send stop recording request

Error message

failed to send stop recording request

What it means

stopRecording sends a StopRecordingRequest for the given channel/streamId and polls for the archive's acknowledgment. If ArchiveProxy.stopRecording returns false the request could not be offered on the control publication, and ArchiveException is thrown since the stop never reached the archive.

Solutions

1. Retry stopRecording with back-off once the control session is reconnected
2. If stopping during shutdown, ensure the archive connection is still alive or accept the recording continues and stop it after reconnect
3. Catch ArchiveException and fall back to tryStopRecording or reconnect-then-stop

Example fix

// before
archive.stopRecording(channel, streamId); // throws if request cannot be sent
// after
try {
    archive.stopRecording(channel, streamId);
} catch (ArchiveException ex) {
    archive = AeronArchive.connect(ctx);
    archive.stopRecording(channel, streamId);
}

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

try {
    archive.stopRecording(channel, streamId);
} catch (ArchiveException ex) {
    if (ex.getMessage().contains("failed to send")) { retryWithBackoff(); }
}

When it happens

Trigger: Calling AeronArchive.stopRecording(channel, streamId) when the control-request publication cannot accept the message: control session disconnected, back-pressure, or buffer full.

Common situations: Application shutdown attempting to stop recordings after the archive connection dropped; archive under load; control channel congestion during burst of stop requests.

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 start recording request
• failed to send extend recording request
• failed to send list recordings request
• failed to send list recording request
• failed to send get start position request

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

Appendix: source

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

     * a recording on a channel without a sessionId parameter will not stop the recording of any sessionId specific
     * recordings that use the same channel and streamId.
     *
     * @param channel  to stop recording for.
     * @param streamId to stop recording for.
     */
    public void stopRecording(final String channel, final int streamId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.stopRecording(channel, streamId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send stop recording request");
            }

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

    /**
     * Try to stop a recording for a channel and stream pairing.
     * <p>
     * Channels that include sessionId parameters are considered different from channels without sessionIds. Stopping
     * a recording on a channel without a sessionId parameter will not stop the recording of any sessionId specific
     * recordings that use the same channel and streamId.
     *
     * @param channel  to stop recording for.

View on GitHub (pinned to 6d60124e15)