aeron-io/aeron · error · IllegalArgumentException

Checksum class name must be specified!

Error message

Checksum class name must be specified!

What it means

validateChecksumClass throws IllegalArgumentException when the checksum class name argument is null, empty, or only whitespace. Verify/checksum operations need a concrete Checksum implementation class name to instantiate. The tool refuses to proceed without one.

Solutions

1. Pass a checksum class name, e.g. io.aeron.security.XmlChecksum or your own Checksum implementation class.
2. Trim and non-empty-check the config value before invoking the tool.
3. Only invoke checksum operations when a checksum provider is actually configured.

Example fix

// before
String checksumClass = config.get("checksum.class"); // null -> throws
ArchiveTool.checksum(out, archiveDir, options, checksumClass);
// after
String checksumClass = config.getOrDefault("checksum.class", "io.aeron.archive.checksum.Sha256Checksum");
ArchiveTool.checksum(out, archiveDir, options, checksumClass);

if (checksumClassName == null || checksumClassName.trim().isEmpty()) {
    throw new IllegalArgumentException("--checksum-class is required for checksum operations");
}

try {
    ArchiveTool.checksum(out, archiveDir, options, checksumClassName);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Checksum class name must be specified")) {
        // re-run with a configured class name
    } else throw e;
}

When it happens

Trigger: Running ArchiveTool checksum/checksumRecording/verify without supplying --checksum-class (or supplying an empty/blank value), when the code path calls validateChecksumClass.

Common situations: Forgot the CLI flag for checksum operations; passed an empty string from a script variable; whitespace-only value from config.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Checksum class name is required when " + APPLY_CHECKSUM + "…
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set
• AeronArchive.Context.controlResponseChannel must be set

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

Appendix: source

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

                        he.state(targetState);
                        out.println("(recordingId=" + recordingId + ") changed state to " + targetState);
                    }
                }
            });

            if (!found.get())
            {
                throw new AeronException("no recording found with recordingId: " + recordingId);
            }
        }
    }

    private static String validateChecksumClass(final String checksumClassName)
    {
        final String className = null == checksumClassName ? null : checksumClassName.trim();
        if (Strings.isEmpty(className))
        {
            throw new IllegalArgumentException("Checksum class name must be specified!");
        }

        return className;
    }

    private static Checksum createChecksum(final Set<VerifyOption> options, final String checksumClassName)
    {
        if (null == checksumClassName)
        {
            if (options.contains(APPLY_CHECKSUM))
            {
                throw new IllegalArgumentException(
                    "Checksum class name is required when " + APPLY_CHECKSUM + " option is specified!");
            }

            return null;
        }

View on GitHub (pinned to 6d60124e15)