aeron-io/aeron · error · ArchiveException

failed to send stop replay request

Error message

failed to send stop replay request

What it means

stopReplay sends a STOP_REPLAY request for a specific replay session id. ArchiveProxy.stopReplay returning false — control-request publication not connected, offer failed from backpressure, or closed publication — means the request was never dispatched, so the library throws this ArchiveException.

Solutions

1. Check the archive is up and control channel is connected; reconnect via AeronArchive.connect if the session was lost.
2. Retry with backoff for transient backpressure — the replay will end on its own when its subscription closes anyway.
3. Validate replaySessionId belongs to the current control session; stale session ids from a previous connection cannot be stopped.
4. If the replay is already gone (archive restarted), treat the failure as benign and move on.

Example fix

// before
archive.stopReplay(replaySessionId);

// after
try {
    archive.stopReplay(replaySessionId);
} catch (ArchiveException e) {
    archive = AeronArchive.connect(archiveCtx);
    archive.stopAllReplays(recordingId); // best-effort cleanup
}

if (replaySessionId <= 0) throw new IllegalArgumentException("invalid replaySessionId");
boolean connected = archive != null && !archive.isClosed();

boolean stoppable(AeronArchive a, long sid) { return a != null && !a.isClosed() && a.state() == AeronArchive.State.CONNECTED && sid > 0; }

try {
    archive.stopReplay(replaySessionId);
} catch (ArchiveException e) {
    // replay may already be gone after archive restart; log and continue
    logger.warn("stopReplay send failed for session {}", replaySessionId, e);
}

When it happens

Trigger: Calling stopReplay(replaySessionId) when the archive control channel is disconnected (archive stopped/restarted, network fault) or the control stream is backpressured; also when the control session was already terminated.

Common situations: Cleanup code in finally blocks running after an archive outage; replay teardown scripts racing with archive shutdown; long-lived sessions whose control publication silently dropped.

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 replay request
• failed to send bounded replay request
• failed to send stop all replays request
• failed to fetch remote recording descriptor
• failed to resolve subscription endpoint: channel=" +…

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

Appendix: source

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

    /**
     * Stop an existing replay session.
     *
     * @param replaySessionId to stop replay for which would have been returned from
     *                        {@link #startReplay(long, long, long, String, int)}.
     */
    public void stopReplay(final long replaySessionId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.stopReplay(replaySessionId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send stop replay request");
            }

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

    /**
     * Stop all replay sessions for a given recording id or all replays in general.
     *
     * @param recordingId to stop replay for or {@link Aeron#NULL_VALUE} for all replays.
     */
    public void stopAllReplays(final long recordingId)
    {
        lock.lock();

View on GitHub (pinned to 6d60124e15)