aeron-io/aeron · error · ArchiveException

Found potentially incomplete last fragment straddling page…

Error message

Found potentially incomplete last fragment straddling page boundary in file: " + segmentFile.getAbsolutePath() + "\nRun `ArchiveTool verify` for corrective action!

What it means

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.

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

Example fix

// before
// archive dir opened directly, torn last fragment blocks verification
// after
// from CLI:
// java -cp aeron-samples.jar io.aeron.archive.tool.ArchiveTool verify /var/aeron/archive
// then re-run your tooling; the incomplete fragment has been handled

Defensive patterns

Strategy: fallback

Validate before calling

// Verify the archive directory before opening recordings programmatically:
// java -cp aeron-samples.jar io.aeron.archive.tool.ArchiveTool verify <archive-dir>

Try / catch

try {
    aeronArchive.listRecording subscription/replay...
} catch (ArchiveException e) {
    if (e.getMessage().contains("incomplete last fragment straddling page boundary")) {
        // invoke ArchiveTool verify for corrective action, then retry or skip recording
    } else {
        throw e;
    }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Catalog.java:1090

        final UnsafeBuffer buffer)
    {
        final long recordingId = decoder.recordingId();
        if (VALID == headerDecoder.state() && NULL_POSITION == decoder.stopPosition())
        {
            final List<String> segmentFiles = segmentFilesByRecordingId.getOrDefault(recordingId, emptyList());
            final String maxSegmentFile = findSegmentFileWithHighestPosition(segmentFiles);

            encoder.stopPosition(computeStopPosition(
                archiveDir,
                maxSegmentFile,
                decoder.startPosition(),
                decoder.termBufferLength(),
                decoder.segmentFileLength(),
                checksum,
                buffer,
                (segmentFile) ->
                {
                    throw new ArchiveException(
                        "Found potentially incomplete last fragment straddling page boundary in file: " +
                        segmentFile.getAbsolutePath() +
                        "\nRun `ArchiveTool verify` for corrective action!");
                }));

            encoder.stopTimestamp(epochClock.time());
        }
    }

    private void forceWrites(final FileChannel channel)
    {
        fsync(channel, forceWrites, forceMetadata);
    }

    private void fsync(final FileChannel channel, final boolean forceWrites, final boolean forceMetadata)
    {
        if (null != channel && forceWrites)
        {

View on GitHub (pinned to 6d60124e15)