aeron-io/aeron · error · IllegalArgumentException

Checksum class name is required when " + APPLY_CHECKSUM + "…

Error message

Checksum class name is required when " + APPLY_CHECKSUM + " option is specified!

What it means

createChecksum throws IllegalArgumentException when the APPLY_CHECKSUM verify option was requested but no checksum class name was provided. The tool cannot verify or apply checksums without an implementation of the Checksum interface. The class name is otherwise optional (returns null when not needed).

Solutions

Supply a checksum class name (same one used when the recording was written) together with APPLY_CHECKSUM.
Remove the APPLY_CHECKSUM option if checksum verification is not required.
Ensure checksumClassName is non-null before building options containing APPLY_CHECKSUM.

Example fix

// before
options.add(VerifyOption.APPLY_CHECKSUM); // but checksumClassName == null -> throws
// after
options.add(VerifyOption.APPLY_CHECKSUM);
String checksumClassName = "io.aeron.archive.checksum.Sha256Checksum"; // required with APPLY_CHECKSUM

Defensive patterns

Strategy: validation

Validate before calling

if (options.contains(VerifyOption.APPLY_CHECKSUM) && (checksumClassName == null || checksumClassName.isEmpty())) {
    throw new IllegalArgumentException("APPLY_CHECKSUM requires a checksum class name");
}

Try / catch

try {
    ArchiveTool.verifyRecording(out, archiveDir, verifier, options, createChecksum(options, checksumClassName), recordingId);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Checksum class name is required")) {
        // add --checksum-class or drop APPLY_CHECKSUM and retry
    } else throw e;
}

Prevention

Always pass the same checksum class used when the recording was written.
Pair APPLY_CHECKSUM with its class name in a single script/config unit so they cannot diverge.
Drop APPLY_CHECKSUM when only structural verification is needed.

When it happens

Trigger: Calling ArchiveTool.verifyRecording/createChecksum with options containing VerifyOption.APPLY_CHECKSUM while checksumClassName is null (e.g. verify with APPLY_CHECKSUM but no --checksum-class flag).

Common situations: Enabling APPLY_CHECKSUM in the options set but forgetting the checksum class CLI arg; scripted verification where the class name variable is empty/null.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

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

        return newInstance(checksumClassName);
    }

    private static CatalogEntryProcessor createVerifyEntryProcessor(
        final PrintStream out,
        final File archiveDir,
        final Set<VerifyOption> options,
        final Catalog catalog,
        final Checksum checksum,
        final EpochClock epochClock,
        final MutableInteger errorCount,
        final ActionConfirmation<File> truncateOnPageStraddle)

View on GitHub (pinned to 6d60124e15)