aeron-io/aeron · error · ArchiveException

invalid filename format: " + filename

Error message

invalid filename format: " + filename

What it means

Thrown by Catalog.parseSegmentFilePosition when a recording segment filename does not contain the expected '-' separator between the recordingId and the encoded replay position. The archive relies on the '<recordingId>-<position>.rec' naming convention to recover metadata from segment files, so a file without a dash cannot be parsed.

Solutions

  1. Verify the archive directory contains only files matching the '<recordingId>-<position>.rec' segment naming convention
  2. Remove or move out stray files (catalog.dat, partial/temp files) that do not match the segment pattern
  3. Do not manually rename recording segment files; restore them from backup instead
  4. Check that all files came from the same Aeron version (naming scheme changes across versions)

Example fix

// before: iterating all files and parsing every one
for (String f : dir.list()) { pos = Catalog.parseSegmentFilePosition(f); }
// after: filter to valid segment names first
for (String f : dir.list()) {
    if (f != null && f.matches("\\d+-\\d+\\.rec")) {
        pos = Catalog.parseSegmentFilePosition(f);
    }
}
Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidSegmentFilename(String f) {
    return f != null && f.matches("\\d+-\\d+\\.rec");
}
// call Catalog.parseSegmentFilePosition(f) only if isValidSegmentFilename(f)

Type guard

boolean isSegmentFile(String name) { return name != null && name.indexOf('-') > 0 && name.endsWith(".rec"); }

Try / catch

try {
    pos = Catalog.parseSegmentFilePosition(filename);
} catch (ArchiveException e) {
    log.warn("skipping non-segment file: " + filename);
}

Prevention

When it happens

Trigger: Parsing a file in the archive catalog directory that is not a well-formed recording segment file (e.g. the catalog itself, temp/partial files, or manually renamed/corrupted segment files missing the dash).

Common situations: Corrupted or hand-edited segment filenames after a crash, files copied into the archive directory from elsewhere, or older/newer Aeron versions with different naming schemes sharing one archive directory.

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

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

Appendix: source

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

                throw new ArchiveException("negative position encoded in the file name: " + filename);
            }

            if (filePosition > maxSegmentPosition)
            {
                maxSegmentPosition = filePosition;
                maxFileName = filename;
            }
        }

        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);

View on GitHub (pinned to 6d60124e15)