aeron-io/aeron · error · ArchiveException

failed to send update channel request

Error message

failed to send update channel request

What it means

Thrown when the client cannot offer the updateChannel request (change the recording channel of a live recording) to the archive control channel. The ArchiveProxy send returned false, so the archive never received the request and the recording's channel is unchanged.

Solutions

1. Verify control-channel connectivity and re-establish the AeronArchive session if it dropped.
2. Retry updateChannel after backoff; transient offer failures are common under load.
3. Validate newChannel URI is a valid replay/recording-capable channel before retrying.
4. Check archive logs to confirm the control listener is subscribed on the configured channel/stream.

Example fix

// before
archive.updateChannel(recordingId, newChannel);
// after
try {
    archive.updateChannel(recordingId, newChannel);
} catch (ArchiveException e) {
    archive = AeronArchive.connect(ctx); // refresh dead/stale session
    archive.updateChannel(recordingId, newChannel);
}

if (!archive.controlResponsePoller().subscription().isConnected()) {
    archive = AeronArchive.connect(ctx);
}
AeronUri.parse(newChannel); // validate channel URI first

try {
    archive.updateChannel(recordingId, newChannel);
} catch (ArchiveException e) {
    archive = AeronArchive.connect(ctx);
    archive.updateChannel(recordingId, newChannel);
}

When it happens

Trigger: Calling AeronArchive.updateChannel(recordingId, newChannel) while the control request publication is disconnected or persistently backpressured.

Common situations: Archive process down; network issues on the control channel; control buffer full under load; stale AeronArchive session reused after the archive restarted with a new session id.

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 purge segments request
• failed to send extend recording request

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

Appendix: source

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

    /**
     * Update the channel for a recording, i.e. replace original and stripped channel information in the catalog.
     *
     * @param recordingId the recording id to update.
     * @param newChannel  to use in the catalogue.
     */
    public void updateChannel(final long recordingId, final String newChannel)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.updateChannel(recordingId, newChannel, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send update channel request");
            }

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

    private void checkDeadline(final long deadlineNs, final String errorMessage, final long correlationId)
    {
        if (deadlineNs - nanoClock.nanoTime() < 0)
        {
            throw new TimeoutException(
                errorMessage + " - correlationId=" + correlationId + " messageTimeout=" +
                SystemUtil.formatDuration(messageTimeoutNs));
        }

View on GitHub (pinned to 6d60124e15)