aeron-io/aeron · error · ArchiveException

failed to send stop replication request

Error message

failed to send stop replication request

What it means

Thrown when a stopReplication request could not be offered to the archive control publication. ArchiveProxy.stopReplication returned false, so the archive never received the instruction to stop the given replicationId. The replication keeps running server-side; this is purely a request-delivery failure.

Solutions

1. Reconnect the archive session and re-issue stopReplication with the same replicationId.
2. Verify the archive is still running; if it was restarted, the replication is already gone and the stop can be skipped.
3. Check the control channel and Aeron error log for publication close/back-pressure events.
4. Implement idempotent cleanup: on send failure, reconnect, then verify via listReplications whether the replication still exists before stopping.
5. Avoid long-lived idle AeronArchive handles in teardown paths; recreate the session before cleanup operations.

Example fix

// before
archive.stopReplication(replicationId);
// after
try {
    archive.stopReplication(replicationId);
} catch (ArchiveException e) {
    if (e.message().contains("failed to send")) {
        archive = AeronArchive.connect(ctx);
        archive.stopReplication(replicationId);
    } 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.stopReplication(replicationId); } catch (ArchiveException e) { if (isSendFailure(e)) { archive = reconnect(archive); archive.stopReplication(replicationId); } else { throw e; } }

When it happens

Trigger: Calling AeronArchive.stopReplication(replicationId) while the control session publication is closed, the archive is unreachable, or the publication is persistently back-pressured so the offer fails after retries.

Common situations: Cancelling a replication during an archive restart; teardown code in a finally block reusing a dead AeronArchive; network interruption between client and destination archive when stopping cross-DC replication.

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 tagged replicate 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/d0fe41729f3864a0. Report an issue: GitHub.

Appendix: source

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

    /**
     * Stop a replication session by id returned from {@link #replicate(long, long, int, String, String)}.
     *
     * @param replicationId to stop replication for.
     * @see #replicate(long, long, int, String, String)
     */
    public void stopReplication(final long replicationId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.stopReplication(replicationId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send stop replication request");
            }

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


    /**
     * Attempt to stop a replication session by id returned from {@link #replicate(long, long, int, String, String)}.
     *
     * @param replicationId to stop replication for.
     * @return {@code true} if the replication was stopped, false if the replication is not active.
     * @see #replicate(long, long, int, String, String)
     */

View on GitHub (pinned to 6d60124e15)