aeron-io/aeron · error · ArchiveException

failed to send migrate segments request

Error message

failed to send migrate segments request

What it means

Thrown when the client fails to offer the migrateSegments request (move segments from a source recording to a target recording with matching channel/streams) to the archive control channel. The request never reached the archive, so no migration occurred.

Solutions

1. Check the archive is reachable and the control session is live; reconnect if necessary.
2. Retry migrateSegments with backoff after a transient offer failure.
3. Confirm srcRecordingId and dstRecordingId exist and have matching streams so the retry succeeds once delivered.
4. Review control channel configuration on both client and archive for mismatches.

// ensure both recordings exist and channel is connected
long src = archive.getRecordingPosition(srcRecordingId); // throws if invalid
if (!archive.controlResponsePoller().subscription().isConnected()) { reconnect(); }

try {
    archive.migrateSegments(srcRecordingId, dstRecordingId);
} catch (ArchiveException e) {
    backoffAndRetry(() -> archive.migrateSegments(srcRecordingId, dstRecordingId));
}

When it happens

Trigger: Calling AeronArchive.migrateSegments(srcRecordingId, dstRecordingId) when the control publication is not connected or the offer fails after retries due to backpressure.

Common situations: Archive down or restarting during a maintenance window; control-channel congestion; using a session whose archive has been recycled; incorrect control channel configuration in AeronArchive.Context.

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 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/baa9cdaffd2606ba. Report an issue: GitHub.

Appendix: source

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

     * The source recording will be effectively truncated back to its start position after the migration.
     *
     * @param srcRecordingId source recording from which the segments will be migrated.
     * @param dstRecordingId destination recording to which the segments will be attached.
     * @return count of attached segment files.
     */
    public long migrateSegments(final long srcRecordingId, final long dstRecordingId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.migrateSegments(srcRecordingId, dstRecordingId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send migrate segments request");
            }

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

    /**
     * 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)
    {

View on GitHub (pinned to 6d60124e15)