aeron-io/aeron · error · ArchiveException

failed to send start recording request

Error message

failed to send start recording request

What it means

startRecording sends a StartRecordingRequest to the archive via ArchiveProxy and then polls for the response. ArchiveProxy.startRecording returns false when the control request could not be offered/published on the control publication (e.g. publication back-pressure or not connected). The library throws ArchiveException in that case because the request never reached the archive.

Solutions

1. Retry startRecording after a short back-off; ensure the control session is connected first (ensureConnected/pollForResponse path)
2. Verify archive is running and control channel throughput is not saturated; reduce concurrent control requests
3. Catch ArchiveException and re-establish the archive connection via AeronArchive.connect() before retrying

Example fix

// before
archive.startRecording(channel, streamId, SourceLocation.LOCAL); // throws on transient send failure
// after
while (!sendStarted) {
    try { archive.startRecording(channel, streamId, SourceLocation.LOCAL); sendStarted = true; }
    catch (ArchiveException ex) { Thread.sleep(100); }
}

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

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

When it happens

Trigger: Calling AeronArchive.startRecording(channel, streamId, sourceLocation) when the control-request publication cannot accept the message — control session down, publication not connected, or send buffer full at offer time.

Common situations: Archive slow or control channel congested (offer retry limit exhausted); control session just established but publication not yet connected; archive under heavy load during many simultaneous recording 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 extend 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/ba79724bbcf4943e. Report an issue: GitHub.

Appendix: source

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

     * @param channel        to be recorded.
     * @param streamId       to be recorded.
     * @param sourceLocation of the publication to be recorded.
     * @return the subscriptionId, i.e. {@link Subscription#registrationId()}, of the recording. This can be
     * passed to {@link #stopRecording(long)}.
     */
    public long startRecording(final String channel, final int streamId, final SourceLocation sourceLocation)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

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

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

    /**
     * Start recording a channel and stream pairing.
     * <p>
     * Channels that include sessionId parameters are considered different from channels without sessionIds. If a
     * publication matches both a sessionId specific channel recording and a non-sessionId specific recording,
     * it will be recorded twice.
     *
     * @param channel        to be recorded.

View on GitHub (pinned to 6d60124e15)