aeron-io/aeron · error · IllegalArgumentException

failed to open recording segment file " + segmentFileName

Error message

failed to open recording segment file " + segmentFileName

What it means

RecordingReader reads recorded data from segment files on disk named by recordingId and position. openRecordingSegment checks existence first and throws IllegalArgumentException naming the missing segment file if it is absent; the subsequent map would otherwise fail with a less clear IOException.

Solutions

1. Verify the archiveDir configured on the archive (Archive.Configuration.ARCHIVE_DIR) is the directory that actually holds the recording.
2. Check the recording still exists via ArchiveClient.listRecording/listRecordings before replaying; retention may have purged it.
3. Confirm recordingId and the recording summary's segmentFileLength are correct — a wrong segmentLength breaks the filename computation.
4. Restore the missing segment from backup/replication or replay only within the surviving segment range.

Example fix

// before
new RecordingReader(summary, new File("/wrong/archive"), pos, len);
// after
File archiveDir = new File(ctx.archiveDir()); // same dir the archive writes to
if (!new File(archiveDir, RecordingSegmentUtil.fileName(recordingId, pos)).exists()) {
    throw new IllegalStateException("segment missing; check archiveDir/retention");
}
new RecordingReader(summary, archiveDir, pos, len);

String name = RecordingReader.segmentFileName(recordingId, segmentPos);
if (!new File(archiveDir, name).exists()) {
    throw new IllegalStateException("segment file missing: " + name + " in " + archiveDir);
}

try { replay(recId, pos, len); }
catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("failed to open recording segment file")) {
        verifyArchiveDirAndRestoreSegment();
    }
}

When it happens

Trigger: Replaying from a position whose segment file does not exist in archiveDir — wrong archive directory configured, segment deleted by retention/cleanup, segmentFileName computed from a mismatched recordingId or out-of-range segmentFilePosition.

Common situations: archiveDir pointing at the wrong volume/mount (e.g. after container redeployment); purged recordings being replayed; replicating archives to a node missing some segments; miscomputed segment file position from a bad segmentLength in the recording summary.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• invalid position: " + position
• invalid length: " + length
• length must be positive
• fromPosition + " position not aligned to valid fragment
• segment file already exists: " + file

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/RecordingReader.java:209

        termBuffer.wrap(mappedSegmentBuffer, termBaseSegmentOffset, termLength);
    }

    private void closeRecordingSegment()
    {
        final MappedByteBuffer mappedSegmentBuffer = this.mappedSegmentBuffer;
        this.mappedSegmentBuffer = null;
        BufferUtil.free(mappedSegmentBuffer);
    }

    private void openRecordingSegment()
    {
        final String segmentFileName = segmentFileName(recordingId, segmentFilePosition);
        final File segmentFile = new File(archiveDir, segmentFileName);

        if (!segmentFile.exists())
        {
            throw new IllegalArgumentException("failed to open recording segment file " + segmentFileName);
        }

        try (FileChannel channel = FileChannel.open(segmentFile.toPath(), FILE_OPTIONS))
        {
            mappedSegmentBuffer = channel.map(READ_ONLY, 0, segmentLength);
        }
        catch (final IOException ex)
        {
            LangUtil.rethrowUnchecked(ex);
        }
    }
}

View on GitHub (pinned to 6d60124e15)