aeron-io/aeron · error · IllegalArgumentException

Invalid fragmentCountLimit=" + fragmentCountLimit

Error message

Invalid fragmentCountLimit=" + fragmentCountLimit

What it means

ArchiveTool.dump validates its fragmentCountLimit argument and throws IllegalArgumentException when it is <= 0. The limit controls how many fragments will be dumped per recording replay, so a non-positive value is meaningless. This is a caller-supplied argument validation error.

Solutions

1. Pass a positive fragmentCountLimit (>= 1) to ArchiveTool.dump.
2. Clamp or default the value before calling, e.g. Math.max(1, limit).
3. Fix the CLI/input parsing that produced the non-positive value.

Example fix

// before
long fragmentCountLimit = 0;
ArchiveTool.dump(archiveDir, fragmentCountLimit, confirm); // throws
// after
long fragmentCountLimit = Math.max(1, parsedLimit);
ArchiveTool.dump(archiveDir, fragmentCountLimit, confirm);

if (fragmentCountLimit <= 0) {
    throw new IllegalArgumentException("fragmentCountLimit must be > 0, got " + fragmentCountLimit);
}

When it happens

Trigger: Calling ArchiveTool.dump(archiveDir, fragmentCountLimit, confirmActionOnFragmentCountLimit) with fragmentCountLimit <= 0, e.g. passing a default-uninitialized 0 or a negative computed limit.

Common situations: Scripting the tool with a variable that defaulted to 0; off-by-one or sign error when computing the limit from user input; CLI parsing bug feeding -1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2
• segment file length not in valid range
• Unable to derive…

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/ArchiveTool.java:543

    /**
     * Dump the contents of an {@link Archive} so it can be inspected or debugged. Each recording will have its
     * contents dumped up to fragmentCountLimit before requesting to continue.
     *
     * @param out                               to which the contents will be printed.
     * @param archiveDir                        containing the {@link Archive}.
     * @param fragmentCountLimit                limit of data fragments to print from each recording before continue.
     * @param confirmActionOnFragmentCountLimit confirm continue to dump at limit.
     */
    public static void dump(
        final PrintStream out,
        final File archiveDir,
        final long fragmentCountLimit,
        final ActionConfirmation<Long> confirmActionOnFragmentCountLimit)
    {
        if (fragmentCountLimit <= 0)
        {
            throw new IllegalArgumentException("Invalid fragmentCountLimit=" + fragmentCountLimit);
        }

        try (Catalog catalog = openCatalogReadOnly(archiveDir, INSTANCE);
            ArchiveMarkFile markFile = openMarkFile(archiveDir, out::println))
        {
            printMarkInformation(markFile, out);
            out.println("Catalog capacity in bytes: " + catalog.capacity());

            out.println();
            out.println("Dumping up to " + fragmentCountLimit + " fragments per recording");

            final SimpleFragmentHandler fragmentHandler = (buffer, offset, length, frameType, flags, reservedValue) ->
            {
                out.println("data at offset [" + offset + "] with length = " + length);
                if (HDR_TYPE_PAD == frameType)
                {
                    out.println("PADDING FRAME");
                }

View on GitHub (pinned to 6d60124e15)