aeron-io/aeron · error · ArchiveException

failed to send purge segments request

Error message

failed to send purge segments request

What it means

Thrown when the client fails to offer the purgeSegments request (truncate recording to a new start position and delete preceding segments) to the archive control channel. The ArchiveProxy send returned false so nothing was delivered to the archive; the recording is left unchanged.

Solutions

1. Confirm the archive is up and the control session is still connected, reconnecting if needed.
2. Retry the call with backoff, since offer failure is usually transient backpressure.
3. Validate newStartPosition is a valid segment-aligned position to avoid a later server-side error once connectivity is fixed.
4. Increase control publication retry/backoff parameters if purges regularly coincide with heavy archive load.

Example fix

// before
archive.purgeSegments(recordingId, newStartPosition);
// after
try {
    archive.purgeSegments(recordingId, newStartPosition);
} catch (ArchiveException e) {
    // offer failed - retry after backoff or reconnect
    archive = AeronArchive.connect(ctx);
    archive.purgeSegments(recordingId, newStartPosition);
}

if (!archive.controlResponsePoller().subscription().isConnected()) {
    archive = AeronArchive.connect(ctx);
}

try {
    archive.purgeSegments(recordingId, newStartPosition);
} catch (ArchiveException e) {
    backoffAndRetry(() -> archive.purgeSegments(recordingId, newStartPosition));
}

When it happens

Trigger: Calling AeronArchive.purgeSegments(recordingId, newStartPosition) when the control request publication is disconnected or backpressured so the offer retry loop gives up.

Common situations: Archive process down; network partition on the control channel; archive overloaded causing the control publication's terminal buffer to be full; stale AeronArchive session after archive restart.

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 delete detached segments request
• failed to send migrate 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/7ae67fecd82ec01f. Report an issue: GitHub.

Appendix: source

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

     * @param newStartPosition for the recording after the segments are detached.
     * @return count of deleted segment files.
     * @see #detachSegments(long, long)
     * @see #deleteDetachedSegments(long)
     * @see #segmentFileBasePosition(long, long, int, int)
     */
    public long purgeSegments(final long recordingId, final long newStartPosition)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.purgeSegments(recordingId, newStartPosition, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send purge segments request");
            }

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

    /**
     * Attach segments to the beginning of a recording to restore history that was previously detached.
     * <p>
     * Segment files must match the existing recording and join exactly to the start position of the recording
     * they are being attached to.
     *
     * @param recordingId to which the operation applies.
     * @return count of attached segment files.

View on GitHub (pinned to 6d60124e15)