apache/cassandra · error · ConfigurationException

Invalid comparator class %s: must define a public static ins

Error message

Invalid comparator class %s: must define a public static instance field or a public static method getInstance(TypeParser).

What it means

TypeParser.getRawAbstractType(Class) instantiates an AbstractType via its public static 'instance' field when no getInstance(TypeParser) method exists. This ConfigurationException is thrown when the class has neither — the comparator class doesn't follow the AbstractType singleton/instance convention required by the parser.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/TypeParser.java:514

        // access or getInstance(TypeParser) invocation below performs the initialization for valid types.
        @SuppressWarnings("unchecked")
        Class<? extends AbstractType<?>> typeClass =
            (Class<? extends AbstractType<?>>) FBUtilities.classForNameWithoutInitialization(className,
                                                                                             "abstract-type",
                                                                                             AbstractType.class);
        return typeClass;
    }

    private static AbstractType<?> getRawAbstractType(Class<? extends AbstractType<?>> typeClass) throws ConfigurationException
    {
        try
        {
            Field field = typeClass.getDeclaredField("instance");
            return (AbstractType<?>) field.get(null);
        }
        catch (NoSuchFieldException | IllegalAccessException e)
        {
            throw new ConfigurationException("Invalid comparator class " + typeClass.getName() + ": must define a public static instance field or a public static method getInstance(TypeParser).");
        }
    }

    private static AbstractType<?> getRawAbstractType(Class<? extends AbstractType<?>> typeClass, TypeParser parser) throws ConfigurationException
    {
        try
        {
            Method method = typeClass.getDeclaredMethod("getInstance", TypeParser.class);
            return (AbstractType<?>) method.invoke(null, parser);
        }
        catch (NoSuchMethodException | IllegalAccessException e)
        {
            throw new ConfigurationException("Invalid comparator class " + typeClass.getName() + ": must define a public static instance field or a public static method getInstance(TypeParser).");
        }
        catch (InvocationTargetException e)
        {
            ConfigurationException ex = new ConfigurationException("Invalid definition for comparator " + typeClass.getName() + ".");
            ex.initCause(e.getTargetException());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add a public static field named exactly 'instance' of the comparator's type to the class, or
2. Add a public static AbstractType getInstance(TypeParser parser) method to the class
3. Verify the deployed jar version matches the code you expect (the field may have been renamed upstream)
4. Check for classloader conflicts — two versions of the same class on the classpath
5. If the class is third-party, wrap it with an adapter class that exposes the 'instance' field

Example fix

// before
class CustomComparator extends AbstractType<ByteBuffer> { public static final CustomComparator INSTANCE = new CustomComparator(); ... }
// after
class CustomComparator extends AbstractType<ByteBuffer> { public static final CustomComparator instance = new CustomComparator(); ... }

static <T extends AbstractType<?>> void validateComparatorClass(Class<T> clazz) throws Exception {
    try {
        clazz.getDeclaredField("instance");
    } catch (NoSuchFieldException e) {
        try {
            clazz.getDeclaredMethod("getInstance", TypeParser.class);
        } catch (NoSuchMethodException e2) {
            throw new IllegalArgumentException(clazz.getName() + " needs a static 'instance' field or getInstance(TypeParser) method");
        }
    }
}

try {
    AbstractType<?> t = TypeParser.parse(customTypeName);
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Invalid comparator class"))
        throw new SchemaConfigurationException("Custom comparator missing static instance/getInstance convention", e);
    throw e;
}

When it happens

Trigger: Parsing a type name whose class (custom or built-in) lacks both a declared static Field named 'instance' and a static getInstance(TypeParser) method — typically a custom AbstractType subclass with the singleton declared under a different field name or not static.

Common situations: Deploying a custom comparator class that implements neither convention, renaming the singleton field (e.g. to INSTANCE) in a custom type, classpath loading an older/newer version of a type class where the field was renamed, or referencing third-party AbstractType implementations not designed for TypeParser.

Related errors

• %s is reserved for internal functionality
• FrozenType() only accepts one parameter
• MapType takes exactly 2 type parameters
• ReversedType takes exactly one argument, " + types.size() +
• SetType takes exactly 1 type parameter

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/aa386be35a134db2. Report an issue: GitHub.