aeron-io/aeron · error · ArchiveException

unknown recording id: " + recordingId

Error message

unknown recording id: " + recordingId

What it means

Catalog.extendRecording (used when extending an existing recording) resolves the recordingId to a descriptor offset via recordingDescriptorOffset. If the ID is not present in the catalog it returns -1, and this ArchiveException is thrown because an existing recording cannot be extended that does not exist.

Solutions

  1. List catalog entries (`ArchiveTool describe <archiveDir>`) and confirm the recordingId exists before extending.
  2. Correct the recordingId passed to extendRecording.
  3. Start a fresh recording instead of extending if the original was deleted.

Example fix

// before
archive.extendRecording(9999L, ...); // unknown id
// after: verify first
if (archive.listRecording(9999L) != null) { archive.extendRecording(9999L, ...); }
Defensive patterns

Strategy: validation

Validate before calling

// Validate recordingId exists before extending
if (archive.listRecording(recordingId) == null) {
    throw new IllegalArgumentException("recordingId " + recordingId + " not present in catalog");
}

Try / catch

try {
    subscription = archive.extendRecording(recordingId, ...);
} catch (ArchiveException e) {
    if (e.getMessage().startsWith("unknown recording id")) {
        // fall back to startRecording() or re-resolve the id from the catalog
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling ArchiveClient.extendRecording/recordingSession with a recordingId that is absent from the catalog, or extending a recording after its catalog entry was removed.

Common situations: Replaying-and-extending a recording whose ID was mistyped or came from a different archive; extending a recording that was purged; stale configuration pointing at an old recordingId after catalog truncation.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Catalog.java:683

        final long recordingId,
        final long startPosition,
        final long stopPosition,
        final long startTimestamp,
        final long stopTimestamp,
        final int imageInitialTermId,
        final int segmentFileLength,
        final int termBufferLength,
        final int mtuLength,
        final int sessionId,
        final int streamId,
        final String strippedChannel,
        final String originalChannel,
        final String sourceIdentity)
    {
        final int recordingOffset = recordingDescriptorOffset(recordingId);
        if (-1 == recordingOffset)
        {
            throw new ArchiveException("unknown recording id: " + recordingId);
        }

        final int recordingLength = fieldAccessBuffer.getInt(
            recordingOffset + RecordingDescriptorHeaderDecoder.lengthEncodingOffset(), BYTE_ORDER);
        final int oldFrameLength = align(recordingLength + DESCRIPTOR_HEADER_LENGTH, alignment);
        final int newFrameLength = recordingDescriptorFrameLength(strippedChannel, originalChannel, sourceIdentity);
        final int length, checksumLength;
        if (newFrameLength > oldFrameLength)
        {
            length = checksumLength = newFrameLength - DESCRIPTOR_HEADER_LENGTH;

            final int shiftBytes = newFrameLength - oldFrameLength;
            final int endOfLastRecording = nextRecordingDescriptorOffset;
            if (endOfLastRecording + shiftBytes > capacity)
            {
                growCatalog(MAX_CATALOG_LENGTH, shiftBytes);
            }

View on GitHub (pinned to 6d60124e15)