aeron-io/aeron · error · ArchiveException

failed to send attach segments request

Error message

failed to send attach segments request

What it means

Thrown when the client cannot offer the attachSegments request (re-attach previously detached segment files to a recording) to the archive control channel. ArchiveProxy.attachSegments returned false, meaning the request never reached the archive and the segments remain detached.

Solutions

1. Verify archive connectivity and reconnect the AeronArchive session if disconnected.
2. Retry attachSegments after a short delay; the offer failure is commonly transient.
3. Check controlRequestChannel and controlRequestStreamId against the archive's configured control channel.
4. Ensure segment files being attached are on storage visible to the archive before retrying.

Example fix

// before
archive.attachSegments(recordingId);
// after
if (archive == null || !archive.controlResponsePoller().subscription().isConnected()) {
    archive = AeronArchive.connect(ctx);
}
archive.attachSegments(recordingId);

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

try {
    archive.attachSegments(recordingId);
} catch (ArchiveException e) {
    backoffAndRetry(() -> archive.attachSegments(recordingId));
}

When it happens

Trigger: Calling AeronArchive.attachSegments(recordingId) with a disconnected or backpressured control request publication.

Common situations: Archive agent not running or restarting; control channel misconfigured (wrong channel/streamId); buffer backpressure during heavy archive traffic; stale session after archive failover.

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 delete detached 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/cb6ab84a4f917248. Report an issue: GitHub.

Appendix: source

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

     * they are being attached to.
     *
     * @param recordingId to which the operation applies.
     * @return count of attached segment files.
     * @see #detachSegments(long, long)
     */
    public long attachSegments(final long recordingId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

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

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

    /**
     * Migrate segments from a source recording and attach them to the beginning or end of a destination recording.
     * <p>
     * The source recording must match the destination recording for segment length, term length, mtu length,
     * stream id. The source recording must join to the destination recording on a segment boundary and without gaps,
     * i.e., the stop position and term id of one must match the start position and term id of the other.
     * <p>
     * The source recording must be stopped. The destination recording must be stopped if migrating segments

View on GitHub (pinned to 6d60124e15)