aeron-io/aeron · error · ArchiveException

failed to send find last matching recording request

Error message

failed to send find last matching recording request

What it means

AeronArchive.findLastMatchingRecording() throws this ArchiveException when the findLastMatchingRecording request could not be sent to the archive control-request publication. archiveProxy.findLastMatchingRecording() returned false, meaning the offer was rejected because the publication is not connected, has been closed, or was back-pressured throughout the retry window, so pollForResponse never executes.

Solutions

Verify the archive is running and the control-channel endpoint/aeron.dir settings match on both sides.
Retry findLastMatchingRecording with backoff; transient back-pressure is the usual cause.
Recreate the archive session with AeronArchive.connect() if the control session was closed server-side.
Rate-limit recording searches so the control publication buffer does not fill.
Check archive logs for the session-close or publication error that caused the rejected offer.

Defensive patterns

Strategy: retry

Validate before calling

if (!archive.archiveProxy().controlPublication().isConnected()) {
    throw new IllegalStateException("archive control publication not connected");
}

Try / catch

try {
    long id = archive.findLastMatchingRecording(minRecordingId, channelFragment, streamId, sessionId);
} catch (ArchiveException e) {
    if (e.getMessage().contains("failed to send find last matching recording request")) {
        Thread.sleep(backoffMs); // retry or reconnect
    } else { throw e; }
}

Prevention

Confirm the archive is healthy before running recording searches.
Throttle search queries so the control publication stays unsaturated.
Use retry-with-backoff wrappers around all archive lookups.
Detect and recover from control-session closure proactively.

When it happens

Trigger: Calling findLastMatchingRecording(minRecordingId, channelFragment, streamId, sessionId) while the archive control publication cannot accept the message: archive down/restarting, control session closed or expired, control-request buffer full of queued commands, or wrong control channel configuration.

Common situations: Locating the latest recording for a channel during archive failover; clients whose control session the archive has timed out; repeated search queries piling onto a saturated control stream.

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

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

Appendix: source

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

     * @param streamId        of the recording to match.
     * @param sessionId       of the recording to match.
     * @return the recordingId if found otherwise {@link Aeron#NULL_VALUE} if not found.
     */
    public long findLastMatchingRecording(
        final long minRecordingId, final String channelFragment, final int streamId, final int sessionId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.findLastMatchingRecording(
                minRecordingId, channelFragment, streamId, sessionId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send find last matching recording request");
            }

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

    /**
     * Truncate a stopped recording to a given position that is less than the stopped position. The provided position
     * must be on a fragment boundary. Truncating a recording to the start position effectively deletes the recording.
     * <p>
     * Truncating a recording will stop any concurrent replays of that recording.
     *
     * @param recordingId of the stopped recording to be truncated.
     * @param position    to which the recording will be truncated.

View on GitHub (pinned to 6d60124e15)