aeron-io/aeron · error · AeronException

no recording found with recordingId: " + targetRecordingId

Error message

no recording found with recordingId: " + targetRecordingId

What it means

ArchiveTool.deleteOrphanedSegments looks up targetRecordingId in the Catalog and throws AeronException when a specific (non-NULL_RECORD_ID) recordingId was requested but no matching catalog entry was found. When targetRecordingId is NULL_RECORD_ID the tool processes all recordings and does not throw. It means the requested recording does not exist in this archive's Catalog.

Solutions

Verify the recordingId exists in the Catalog (describeRecording or catalog listing) before invoking deleteOrphanedSegments.
Point the tool at the correct archive directory.
Call with NULL_RECORD_ID to process all recordings instead of a specific one.

Example fix

// before
ArchiveTool.deleteOrphanedSegments(out, archiveDir, clock, 12345L); // id gone -> throws
// after
if (catalogHasRecording(archiveDir, 12345L)) {
    ArchiveTool.deleteOrphanedSegments(out, archiveDir, clock, 12345L);
}

Defensive patterns

Strategy: validation

Validate before calling

if (targetRecordingId != Aeron.NULL_VALUE && !catalogContainsRecording(archiveDir, targetRecordingId)) {
    throw new IllegalArgumentException("recordingId " + targetRecordingId + " not found in " + archiveDir);
}

Try / catch

try {
    ArchiveTool.deleteOrphanedSegments(out, archiveDir, clock, targetRecordingId);
} catch (AeronException e) {
    if (e.getMessage().contains("no recording found")) { /* skip or alert */ } else throw e;
}

Prevention

Re-resolve recordingIds from the catalog immediately before segment maintenance.
Avoid hardcoding recordingIds in scripts; read them from the catalog at runtime.
Run orphan cleanup without a specific id (NULL_RECORD_ID) to process all existing recordings.

When it happens

Trigger: Running ArchiveTool deleteOrphanedSegments <archiveDir> <recordingId> with a recordingId absent from the Catalog; programmatic call to deleteOrphanedSegments with a stale or wrong id.

Common situations: Recording already deleted/compacted; wrong archive directory passed; typo in the id; id from a different archive instance.

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

Appendix: source

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

            final MutableBoolean found = new MutableBoolean(false);
            catalog.forEach((recordingDescriptorOffset,
                headerEncoder,
                headerDecoder,
                descriptorEncoder,
                descriptorDecoder) ->
            {
                final long recordingId = descriptorDecoder.recordingId();
                if (NULL_RECORD_ID == targetRecordingId || targetRecordingId == recordingId)
                {
                    found.set(true);
                    final List<String> files = segmentFilesByRecordingId.getOrDefault(recordingId, emptyList());
                    deleteOrphanedSegmentFiles(out, archiveDir, descriptorDecoder, files);
                }
            });

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

    static void compact(final PrintStream out, final File archiveDir, final EpochClock epochClock)
    {
        final File compactFile = new File(archiveDir, CATALOG_FILE_NAME + ".compact");
        try
        {
            final MutableInteger offset = new MutableInteger(CatalogHeaderEncoder.BLOCK_LENGTH);
            final MutableInteger deletedRecords = new MutableInteger();
            final MutableInteger reclaimedBytes = new MutableInteger();

            final Path compactFilePath = compactFile.toPath();
            try (FileChannel channel = FileChannel.open(compactFilePath, READ, WRITE, CREATE_NEW);
                Catalog catalog = openCatalogReadOnly(archiveDir, epochClock))
            {
                final MappedByteBuffer mappedByteBuffer = channel.map(READ_WRITE, 0, catalog.capacity());

View on GitHub (pinned to 6d60124e15)