{"record":{"id":"e85601d2d7fe82d0","repo":"aeron-io/aeron","slug":"failed-to-create-checksum-instance-for-class-classname","errorCode":null,"errorMessage":"failed to create Checksum instance for class: \" + className","messagePattern":"failed to create Checksum instance for class: \" \\+ className","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/checksum/Checksums.java","lineNumber":92,"sourceCode":"            case \"CRC-32\":\n            case \"io.aeron.archive.checksum.Crc32\":\n            case \"org.agrona.checksum.Crc32\":\n                yield crc32();\n            case \"CRC-32C\":\n            case \"io.aeron.archive.checksum.Crc32c\":\n            case \"org.agrona.checksum.Crc32c\":\n                yield crc32c();\n            default:\n            {\n                try\n                {\n                    final Class<?> klass = Class.forName(className);\n                    final Object instance = klass.getDeclaredConstructor().newInstance();\n                    yield (Checksum)instance;\n                }\n                catch (final ReflectiveOperationException ex)\n                {\n                    throw new IllegalArgumentException(\n                        \"failed to create Checksum instance for class: \" + className, ex);\n                }\n            }\n        };\n    }\n}\n","sourceCodeStart":74,"sourceCodeEnd":99,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/checksum/Checksums.java#L74-L99","documentation":"Checksums.newInstance falls back to reflective loading (Class.forName + getDeclaredConstructor().newInstance()) for unknown class names. If the class cannot be found or instantiated, the underlying ReflectiveOperationException is wrapped in an IllegalArgumentException naming the requested class. The library throws this so callers get a clear message identifying the unresolvable checksum class.","triggerScenarios":"Calling Checksum.newInstance(className) where className is not one of the known constants ('CRC-32', 'CRC-32C', 'Crc32', 'Crc32c' variants) and either does not exist on the classpath or lacks a public no-arg constructor.","commonSituations":"Typo in the fully-qualified class name in archive configuration; a custom Checksum implementation not packaged in the classpath; a custom implementation without a public no-arg constructor; case-sensitive name mismatch (e.g. 'CRC32' vs 'CRC-32').","solutions":["Verify the class name is a valid fully-qualified name present on the archive classpath, or use a known alias like 'CRC-32'/'CRC-32C'","Ensure the custom Checksum class is public with a public no-arg constructor and implements io.aeron.archive.checksum.Checksum","Use the built-in factories Checksum.crc32() or Checksum.crc32c() instead of a string name"],"exampleFix":"// before\nChecksum checksum = Checksum.newInstance(\"com.acme.MyCrc\"); // class not on classpath\n// after\nChecksum checksum = Checksum.newInstance(\"com.acme.MyCrc\"); // after adding the jar and a public no-arg ctor, or:\nChecksum checksum = Checksum.crc32();","handlingStrategy":"validation","validationCode":"String[] known = {\"CRC-32\", \"CRC-32C\", \"io.aeron.archive.checksum.Crc32\", \"io.aeron.archive.checksum.Crc32c\"};\nboolean knownName = Arrays.asList(known).contains(className);\nif (!knownName) {\n    try { Class.forName(className); } catch (ClassNotFoundException e) {\n        throw new IllegalArgumentException(\"checksum class not on classpath: \" + className, e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Checksum checksum = Checksum.newInstance(className);\n} catch (IllegalArgumentException ex) {\n    Checksum checksum = Checksum.crc32(); // fallback\n}","preventionTips":["Use the built-in aliases 'CRC-32'/'CRC-32C' rather than hand-written FQCNs","Ensure custom Checksum classes are public with a public no-arg constructor and shipped on the archive classpath"],"tags":["java","reflection","classpath","configuration"],"backgroundTag":"class-not-found","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}