aeron-io/aeron · error · ArchiveException

failed to send extend recording request

Error message

failed to send extend recording request

What it means

extendRecording sends an ExtendRecordingRequest to record into an existing recording identified by recordingId. If ArchiveProxy.extendRecording returns false — the request could not be offered on the control publication — the library throws ArchiveException because the archive never received the request.

Solutions

1. Verify the control session is connected and retry extendRecording with back-off
2. Confirm recordingId refers to an existing recording and the archive is healthy
3. Catch ArchiveException, reconnect, and re-issue the extend request

Example fix

// before
archive.extendRecording(channel, streamId, SourceLocation.LOCAL, recordingId); // may throw on send failure
// after
try {
    archive.extendRecording(channel, streamId, SourceLocation.LOCAL, recordingId);
} catch (ArchiveException ex) {
    Thread.sleep(200);
    archive.extendRecording(channel, streamId, SourceLocation.LOCAL, recordingId);
}

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

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

When it happens

Trigger: Calling AeronArchive.extendRecording(channel, streamId, sourceLocation, recordingId) when the control publication cannot accept the message: session down, back-pressure, or buffer full.

Common situations: Extending a recording after an archive restart with a stale control session; heavy control-channel load; archive unreachable mid-operation.

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 stop 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/02d4c5d84be6a9fb. Report an issue: GitHub.

Appendix: source

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

     */
    public long extendRecording(
        final long recordingId,
        final String channel,
        final int streamId,
        final SourceLocation sourceLocation)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.extendRecording(
                channel, streamId, sourceLocation, recordingId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send extend recording request");
            }

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

    /**
     * Extend an existing, non-active recording of a channel and stream pairing.
     * <p>
     * The channel must be configured for the initial position from which it will be extended. This can be done
     * with {@link ChannelUriStringBuilder#initialPosition(long, int, int)}. The details required to initialise can
     * be found by calling {@link #listRecording(long, RecordingDescriptorConsumer)}.
     *
     * @param recordingId    of the existing recording.

View on GitHub (pinned to 6d60124e15)