{"record":{"id":"b498aaa1957e2c4f","repo":"aeron-io/aeron","slug":"failed-to-open-recording-segment-file-segmentfilename","errorCode":null,"errorMessage":"failed to open recording segment file \" + segmentFileName","messagePattern":"failed to open recording segment file \" \\+ segmentFileName","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/RecordingReader.java","lineNumber":209,"sourceCode":"\n        termBuffer.wrap(mappedSegmentBuffer, termBaseSegmentOffset, termLength);\n    }\n\n    private void closeRecordingSegment()\n    {\n        final MappedByteBuffer mappedSegmentBuffer = this.mappedSegmentBuffer;\n        this.mappedSegmentBuffer = null;\n        BufferUtil.free(mappedSegmentBuffer);\n    }\n\n    private void openRecordingSegment()\n    {\n        final String segmentFileName = segmentFileName(recordingId, segmentFilePosition);\n        final File segmentFile = new File(archiveDir, segmentFileName);\n\n        if (!segmentFile.exists())\n        {\n            throw new IllegalArgumentException(\"failed to open recording segment file \" + segmentFileName);\n        }\n\n        try (FileChannel channel = FileChannel.open(segmentFile.toPath(), FILE_OPTIONS))\n        {\n            mappedSegmentBuffer = channel.map(READ_ONLY, 0, segmentLength);\n        }\n        catch (final IOException ex)\n        {\n            LangUtil.rethrowUnchecked(ex);\n        }\n    }\n}\n","sourceCodeStart":191,"sourceCodeEnd":222,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/RecordingReader.java#L191-L222","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the archiveDir configured on the archive (Archive.Configuration.ARCHIVE_DIR) is the directory that actually holds the recording.","Check the recording still exists via ArchiveClient.listRecording/listRecordings before replaying; retention may have purged it.","Confirm recordingId and the recording summary's segmentFileLength are correct — a wrong segmentLength breaks the filename computation.","Restore the missing segment from backup/replication or replay only within the surviving segment range."],"exampleFix":"// before\nnew RecordingReader(summary, new File(\"/wrong/archive\"), pos, len);\n// after\nFile archiveDir = new File(ctx.archiveDir()); // same dir the archive writes to\nif (!new File(archiveDir, RecordingSegmentUtil.fileName(recordingId, pos)).exists()) {\n    throw new IllegalStateException(\"segment missing; check archiveDir/retention\");\n}\nnew RecordingReader(summary, archiveDir, pos, len);","handlingStrategy":"validation","validationCode":"String name = RecordingReader.segmentFileName(recordingId, segmentPos);\nif (!new File(archiveDir, name).exists()) {\n    throw new IllegalStateException(\"segment file missing: \" + name + \" in \" + archiveDir);\n}","typeGuard":null,"tryCatchPattern":"try { replay(recId, pos, len); }\ncatch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"failed to open recording segment file\")) {\n        verifyArchiveDirAndRestoreSegment();\n    }\n}","preventionTips":["Confirm ARCHIVE_DIR points to the directory the archive actually writes to, across restarts and mounts.","Check recording availability via listRecordings before replay; respect retention policies.","Replicate/purge recordings atomically so segments never disappear mid-replay.","Keep recording summaries' segmentFileLength consistent with how segments were written."],"tags":["file-not-found","archive","segment-file","replay"],"backgroundTag":"file-not-found","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}