aeron-io/aeron · error · IllegalArgumentException

failed to create Checksum instance for class: " + className

Error message

failed to create Checksum instance for class: " + className

What it means

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.

Solutions

1. 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'
2. Ensure the custom Checksum class is public with a public no-arg constructor and implements io.aeron.archive.checksum.Checksum
3. Use the built-in factories Checksum.crc32() or Checksum.crc32c() instead of a string name

Example fix

// before
Checksum checksum = Checksum.newInstance("com.acme.MyCrc"); // class not on classpath
// after
Checksum checksum = Checksum.newInstance("com.acme.MyCrc"); // after adding the jar and a public no-arg ctor, or:
Checksum checksum = Checksum.crc32();

String[] known = {"CRC-32", "CRC-32C", "io.aeron.archive.checksum.Crc32", "io.aeron.archive.checksum.Crc32c"};
boolean knownName = Arrays.asList(known).contains(className);
if (!knownName) {
    try { Class.forName(className); } catch (ClassNotFoundException e) {
        throw new IllegalArgumentException("checksum class not on classpath: " + className, e);
    }
}

try {
    Checksum checksum = Checksum.newInstance(className);
} catch (IllegalArgumentException ex) {
    Checksum checksum = Checksum.crc32(); // fallback
}

When it happens

Trigger: 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.

Common situations: 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').

Related errors

• failed to instantiate ClusterClock
• className is empty
• existing Mark file type
• :port must be an integer value between 0 and 65535
• :low port value must be lower than high port value

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/checksum/Checksums.java:92

            case "CRC-32":
            case "io.aeron.archive.checksum.Crc32":
            case "org.agrona.checksum.Crc32":
                yield crc32();
            case "CRC-32C":
            case "io.aeron.archive.checksum.Crc32c":
            case "org.agrona.checksum.Crc32c":
                yield crc32c();
            default:
            {
                try
                {
                    final Class<?> klass = Class.forName(className);
                    final Object instance = klass.getDeclaredConstructor().newInstance();
                    yield (Checksum)instance;
                }
                catch (final ReflectiveOperationException ex)
                {
                    throw new IllegalArgumentException(
                        "failed to create Checksum instance for class: " + className, ex);
                }
            }
        };
    }
}

View on GitHub (pinned to 6d60124e15)