{"record":{"id":"82fae95488dea609","repo":"aeron-io/aeron","slug":"found-potentially-incomplete-last-fragment-straddling-page","errorCode":null,"errorMessage":"Found potentially incomplete last fragment straddling page boundary in file: \" + segmentFile.getAbsolutePath() + \"\\nRun `ArchiveTool verify` for corrective action!","messagePattern":"Found potentially incomplete last fragment straddling page boundary in file: \" \\+ segmentFile\\.getAbsolutePath\\(\\) \\+ \"\\\\nRun `ArchiveTool verify` for corrective action!","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":1090,"sourceCode":"        final UnsafeBuffer buffer)\n    {\n        final long recordingId = decoder.recordingId();\n        if (VALID == headerDecoder.state() && NULL_POSITION == decoder.stopPosition())\n        {\n            final List<String> segmentFiles = segmentFilesByRecordingId.getOrDefault(recordingId, emptyList());\n            final String maxSegmentFile = findSegmentFileWithHighestPosition(segmentFiles);\n\n            encoder.stopPosition(computeStopPosition(\n                archiveDir,\n                maxSegmentFile,\n                decoder.startPosition(),\n                decoder.termBufferLength(),\n                decoder.segmentFileLength(),\n                checksum,\n                buffer,\n                (segmentFile) ->\n                {\n                    throw new ArchiveException(\n                        \"Found potentially incomplete last fragment straddling page boundary in file: \" +\n                        segmentFile.getAbsolutePath() +\n                        \"\\nRun `ArchiveTool verify` for corrective action!\");\n                }));\n\n            encoder.stopTimestamp(epochClock.time());\n        }\n    }\n\n    private void forceWrites(final FileChannel channel)\n    {\n        fsync(channel, forceWrites, forceMetadata);\n    }\n\n    private void fsync(final FileChannel channel, final boolean forceWrites, final boolean forceMetadata)\n    {\n        if (null != channel && forceWrites)\n        {","sourceCodeStart":1072,"sourceCodeEnd":1108,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L1072-L1108","documentation":"Thrown during catalog verification of a recording's last segment file when a fragment appears to straddle a page boundary without being complete — indicating the recording stop was not cleanly finalized or the file was truncated mid-write. Aeron segment files align data to term buffer pages; an incomplete fragment at a page boundary suggests data loss. The message directs you to ArchiveTool verify for corrective action.","triggerScenarios":"Opening/verifying a recording in the catalog whose most recent segment file contains a final fragment crossing a page boundary that fails checksum/consistency checks; happens when the archiver crashed mid-recording, disk filled, or a segment file was truncated.","commonSituations":"Ungraceful shutdown (kill -9, power loss) of the media driver/archive during active recording; filesystem corruption; manually copying partially-flushed segment files; running out of disk mid-recording leaving a torn write.","solutions":["Run ArchiveTool verify <archive-dir> which detects and can truncate/eject the incomplete fragment (corrective action recommended by the message)","Use ArchiveTool to repair or delete the affected recording so the catalog no longer references the torn segment","Check disk health/space and ensure the archive is stopped cleanly (close the Archive and media driver gracefully) in future","Re-record the affected stream if the torn fragment contains data you cannot afford to lose"],"exampleFix":"// before\n// archive dir opened directly, torn last fragment blocks verification\n// after\n// from CLI:\n// java -cp aeron-samples.jar io.aeron.archive.tool.ArchiveTool verify /var/aeron/archive\n// then re-run your tooling; the incomplete fragment has been handled","handlingStrategy":"fallback","validationCode":"// Verify the archive directory before opening recordings programmatically:\n// java -cp aeron-samples.jar io.aeron.archive.tool.ArchiveTool verify <archive-dir>","typeGuard":null,"tryCatchPattern":"try {\n    aeronArchive.listRecording subscription/replay...\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"incomplete last fragment straddling page boundary\")) {\n        // invoke ArchiveTool verify for corrective action, then retry or skip recording\n    } else {\n        throw e;\n    }\n}","preventionTips":["Ensure graceful shutdown of driver/archive before stopping the host","Monitor disk free space during recording to avoid torn writes","Copy segment files only after recording stop is confirmed","Run ArchiveTool verify periodically on long-lived archive dirs"],"tags":["aeron-archive","segment-file","data-corruption"],"backgroundTag":"checksum-mismatch","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"}