aeron-io/aeron · error · ArchiveException

failed to send tagged replicate request

Error message

failed to send tagged replicate request

What it means

Thrown when a tagged replicate request could not be offered to the archive control publication. ArchiveProxy.taggedReplicate returned false after retries, so the archive never received the replication request carrying the replay/subscription tags. This is a transport-level failure on the control channel.

Solutions

1. Reconnect the archive session (AeronArchive.connect) and retry taggedReplicate.
2. Check the archive's load and control channel back-pressure counters; throttle concurrent client operations.
3. Verify srcControlChannel connectivity from the destination archive host before replicating.
4. Review Aeron error log for publication-level errors preceding the failure.
5. Consider a dedicated control session for replication-heavy workloads to avoid contention with other clients.

Example fix

// before
archive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);
// after
try {
    archive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);
} catch (ArchiveException e) {
    if (e.message().contains("failed to send")) {
        archive = AeronArchive.connect(ctx);
        archive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);
    } else {
        throw e;
    }
}

if (archive == null || archive.context().isClosed()) { archive = AeronArchive.connect(ctx); }

static boolean isSendFailure(ArchiveException e) { return e.getMessage() != null && e.getMessage().contains("failed to send"); }

try { archive.taggedReplicate(...); } catch (ArchiveException e) { if (isSendFailure(e)) { archive = AeronArchive.connect(ctx); archive.taggedReplicate(...); } else { throw e; } }

When it happens

Trigger: Calling AeronArchive.taggedReplicate(srcRecordingId, dstRecordingId, channelTagId, subscriptionTagId, srcControlStreamId, srcControlChannel, liveDestination) while the control publication is closed, disconnected, or persistently back-pressured.

Common situations: Control session expired during a long catalog operation; destination archive under heavy load so the exclusive publication cannot accept offers; tags configured but the underlying session was already closed by the archive.

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 replicate request
• failed to send stop replication request
• failed to send invalidate recording request
• failed to send list recording subscriptions request
• failed to send detach segments request

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

Appendix: source

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

        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.taggedReplicate(
                srcRecordingId,
                dstRecordingId,
                channelTagId,
                subscriptionTagId,
                srcControlStreamId,
                srcControlChannel,
                liveDestination,
                lastCorrelationId,
                controlSessionId))
            {
                throw new ArchiveException("failed to send tagged replicate request");
            }

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

    /**
     * Replicate a recording from a source archive to a destination which can be considered a backup for a primary
     * archive. The source recording will be replayed via the provided replay channel and use the original stream id.
     * If the destination recording id is {@link io.aeron.Aeron#NULL_VALUE} then a new destination recording is created,
     * otherwise the provided destination recording id will be extended. The details of the source recording
     * descriptor will be replicated. The subscription used in the archive will be tagged with the provided tags.
     * <p>
     * For a source recording that is still active the replay can merge with the live stream and then follow it

View on GitHub (pinned to 6d60124e15)