aeron-io/aeron · error · AeronException

no recording found with recordingId: " + recordingId

Error message

no recording found with recordingId: " + recordingId

What it means

ArchiveTool.describeRecording scans the Catalog for the given recordingId and throws AeronException when no catalog entry with that id is found. It indicates the requested recording does not exist in the archive directory being inspected. A developer hit this by passing a recordingId not present in the catalog.

Solutions

1. List existing recordings with ArchiveTool describeRecording on the correct archive dir or use the catalog entries to find valid recordingIds.
2. Verify you are pointing at the correct archive directory that actually contains the recording.
3. Re-check the recordingId value (it may have been removed or belong to another archive).

Example fix

// before
ArchiveTool.describeRecording(out, archiveDir, 12345L); // id not in catalog -> throws
// after
// find the correct id first (e.g. from the publishing stream or catalog listing), then:
ArchiveTool.describeRecording(out, archiveDir, correctRecordingId);

boolean exists = catalogContainsRecording(archiveDir, recordingId); // scan catalog entries first
if (!exists) {
    throw new IllegalArgumentException("recordingId " + recordingId + " not in catalog at " + archiveDir);
}

try {
    ArchiveTool.describeRecording(out, archiveDir, recordingId);
} catch (AeronException e) {
    if (e.getMessage().startsWith("no recording found")) {
        // handle missing recording: list available ids or abort cleanly
    } else throw e;
}

When it happens

Trigger: Running ArchiveTool describeRecording <archiveDir> <recordingId> with a recordingId that has no entry in the archive's Catalog (typo, wrong archive dir, recording deleted/compacted away).

Common situations: Typo in recordingId; pointing the tool at the wrong archive directory; the recording was removed by catalog compaction or recording deletion; querying an id from a different cluster's archive.

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

• no recording found with recordingId: " + targetRecordingId
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set
• AeronArchive.Context.controlResponseChannel must be set

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/ArchiveTool.java:479

     * @param recordingId to identify the entry.
     */
    public static void describeRecording(final PrintStream out, final File archiveDir, final long recordingId)
    {
        try (Catalog catalog = openCatalogReadWrite(archiveDir, INSTANCE, MIN_CAPACITY, null, null))
        {
            final MutableBoolean found = new MutableBoolean(false);
            catalog.forEach((recordingDescriptorOffset, headerEnc, headerDec, encoder, decoder) ->
            {
                if (decoder.recordingId() == recordingId)
                {
                    found.set(true);
                    out.println(decoder);
                }
            });

            if (!found.get())
            {
                throw new AeronException("no recording found with recordingId: " + recordingId);
            }
        }
    }

    /**
     * Count of the number of entries in the {@link Catalog}.
     *
     * @param archiveDir containing the {@link Catalog}.
     * @return the number of entries in the {@link Catalog}.
     */
    public static int entryCount(final File archiveDir)
    {
        try (Catalog catalog = openCatalogReadOnly(archiveDir, INSTANCE))
        {
            return catalog.entryCount();
        }
    }

View on GitHub (pinned to 6d60124e15)