aeron-io/aeron · error · ArchiveException

no position encoded in the segment file: " + filename

Error message

no position encoded in the segment file: " + filename

What it means

Thrown by Catalog.parseSegmentFilePosition when the filename has a '-' separator but the characters after it (minus the '.rec' suffix) form an empty string, i.e. no replay position is encoded. The archive needs that encoded position to recover the recording's last segment offset.

Solutions

1. Fix or restore the segment filename so it encodes a numeric position after the recordingId, e.g. '12-0.rec'
2. Delete or quarantine the malformed segment file if it holds no useful data so catalog recovery can proceed
3. Restore the archive directory from backup instead of hand-repairing names
4. Check that writing tooling uses Aeron's own segment naming (recordingId + '-' + position + RECORDING_SEGMENT_SUFFIX)

Example fix

// before: malformed name
Files.move(dir.resolve("12-.rec"), dir.resolve("12.rec"));
// after: re-encode position 0
Files.move(dir.resolve("12-.rec"), dir.resolve("12-0.rec"));

static boolean hasEncodedPosition(String f) {
    if (f == null || !f.endsWith(".rec")) return false;
    int dash = f.indexOf('-');
    return dash >= 0 && f.length() - dash - 1 - 4 > 0;
}

boolean isCompleteSegmentName(String name) { return name != null && name.matches("\\d+-\\d+\\.rec"); }

try {
    pos = Catalog.parseSegmentFilePosition(filename);
} catch (ArchiveException e) {
    quarantineOrRepair(filename);
}

When it happens

Trigger: Parsing a segment filename like '<recordingId>-.rec' or '<recordingId>-rec' where the position portion between the dash and the suffix is missing or zero-length.

Common situations: Truncated filenames after disk-full crashes, manual renaming that dropped the position, or custom tooling that wrote segment files with an incorrect naming pattern.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalid filename format: " + filename
• incompatible catalog file version " +…
• unknown recording id: " + recordingId
• catalog is full, max capacity reached: " +…
• negative position encoded in the file name: " + filename

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

Appendix: source

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

            }
        }

        return maxFileName;
    }

    static long parseSegmentFilePosition(final String filename)
    {
        final int dashOffset = filename.indexOf('-');
        if (-1 == dashOffset)
        {
            throw new ArchiveException("invalid filename format: " + filename);
        }

        final int positionOffset = dashOffset + 1;
        final int positionLength = filename.length() - positionOffset - RECORDING_SEGMENT_SUFFIX.length();
        if (0 >= positionLength)
        {
            throw new ArchiveException("no position encoded in the segment file: " + filename);
        }

        return parseLongAscii(filename, positionOffset, positionLength);
    }

    static long parseSegmentFileRecordingId(final String filename)
    {
        final int dashOffset = filename.indexOf('-');
        if (-1 == dashOffset || 0 == dashOffset)
        {
            throw new InvalidRecordingNameException("invalid filename format: " + filename);
        }

        return parseLongAscii(filename, 0, dashOffset);
    }

    static long computeStopPosition(
        final File archiveDir,

View on GitHub (pinned to 6d60124e15)