aeron-io/aeron · error · ArchiveException

failed to send delete detached segments request

Error message

failed to send delete detached segments request

What it means

Thrown by AeronArchive when the client could not even offer the deleteDetachedSegments request to the archive control publication. The ArchiveProxy send returned false, typically because the publication is not connected or its offer was retried out (backpressure) past the retry budget. No request reached the archive, so the recording's detached segments are not deleted.

Solutions

1. Check the archive is running and the control channel is connected (subscription.isConnected()) before issuing the request.
2. Retry deleteDetachedSegments after a short backoff; offer failures are frequently transient backpressure.
3. Verify controlRequestChannel/streamId configuration matches a live archive control listener.
4. Capture the ArchiveException, inspect connection state, and reconnect via AeronArchive.connect() if the session is dead.

Example fix

// before
archive.deleteDetachedSegments(recordingId);
// after
if (!archive.controlResponsePoller().subscription().isConnected()) {
    archive = AeronArchive.connect(ctx); // re-establish session
}
archive.deleteDetachedSegments(recordingId);

// pre-check
if (!archiveProxyPublication.isConnected()) { reconnectArchiveSession(); }

try {
    archive.deleteDetachedSegments(recordingId);
} catch (ArchiveException e) {
    retryWithBackoff(() -> archive.deleteDetachedSegments(recordingId), 3);
}

When it happens

Trigger: Calling AeronArchive.deleteDetachedSegments(recordingId) while the control request publication cannot accept the message: archive is down, control channel disconnected, or send buffer full and offer retries exhausted.

Common situations: Archive agent stopped or restarted between session establishment and the call; slow/congested control-channel network; client created with too-short publication retry settings while archive is under load.

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 attach segments request
• failed to send migrate segments request
• failed to send purge segments request
• failed to send update channel request
• failed to send extend recording request

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

Appendix: source

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

     * Delete segments which have been previously detached from a recording.
     *
     * @param recordingId to which the operation applies.
     * @return count of deleted segment files.
     * @see #detachSegments(long, long)
     */
    public long deleteDetachedSegments(final long recordingId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.deleteDetachedSegments(recordingId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send delete detached segments request");
            }

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

    /**
     * Purge (detach and delete) segments from the beginning of a recording up to the provided new start position.
     * <p>
     * The new start position must be first byte position of a segment after the existing start position.
     * <p>
     * It is not possible to detach segments which are active for recording or being replayed.
     *
     * @param recordingId      to which the operation applies.

View on GitHub (pinned to 6d60124e15)