{"record":{"id":"b4d29e37b72f7ad8","repo":"aeron-io/aeron","slug":"checksum-class-name-is-required-when-apply-checksum-option","errorCode":null,"errorMessage":"Checksum class name is required when \" + APPLY_CHECKSUM + \" option is specified!","messagePattern":"Checksum class name is required when \" \\+ APPLY_CHECKSUM \\+ \" option is specified!","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/ArchiveTool.java","lineNumber":1066,"sourceCode":"\n    private static String validateChecksumClass(final String checksumClassName)\n    {\n        final String className = null == checksumClassName ? null : checksumClassName.trim();\n        if (Strings.isEmpty(className))\n        {\n            throw new IllegalArgumentException(\"Checksum class name must be specified!\");\n        }\n\n        return className;\n    }\n\n    private static Checksum createChecksum(final Set<VerifyOption> options, final String checksumClassName)\n    {\n        if (null == checksumClassName)\n        {\n            if (options.contains(APPLY_CHECKSUM))\n            {\n                throw new IllegalArgumentException(\n                    \"Checksum class name is required when \" + APPLY_CHECKSUM + \" option is specified!\");\n            }\n\n            return null;\n        }\n\n        return newInstance(checksumClassName);\n    }\n\n    private static CatalogEntryProcessor createVerifyEntryProcessor(\n        final PrintStream out,\n        final File archiveDir,\n        final Set<VerifyOption> options,\n        final Catalog catalog,\n        final Checksum checksum,\n        final EpochClock epochClock,\n        final MutableInteger errorCount,\n        final ActionConfirmation<File> truncateOnPageStraddle)","sourceCodeStart":1048,"sourceCodeEnd":1084,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/ArchiveTool.java#L1048-L1084","documentation":"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).","triggerScenarios":"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).","commonSituations":"Enabling APPLY_CHECKSUM in the options set but forgetting the checksum class CLI arg; scripted verification where the class name variable is empty/null.","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."],"exampleFix":"// before\noptions.add(VerifyOption.APPLY_CHECKSUM); // but checksumClassName == null -> throws\n// after\noptions.add(VerifyOption.APPLY_CHECKSUM);\nString checksumClassName = \"io.aeron.archive.checksum.Sha256Checksum\"; // required with APPLY_CHECKSUM","handlingStrategy":"validation","validationCode":"if (options.contains(VerifyOption.APPLY_CHECKSUM) && (checksumClassName == null || checksumClassName.isEmpty())) {\n    throw new IllegalArgumentException(\"APPLY_CHECKSUM requires a checksum class name\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    ArchiveTool.verifyRecording(out, archiveDir, verifier, options, createChecksum(options, checksumClassName), recordingId);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Checksum class name is required\")) {\n        // add --checksum-class or drop APPLY_CHECKSUM and retry\n    } else throw e;\n}","preventionTips":["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."],"tags":["aeron","archive","checksum","conflicting-options"],"backgroundTag":"missing-required-flag","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}