apache/cassandra · error · ConfigurationException

%s is reserved for internal functionality

Error message

%s is reserved for internal functionality

What it means

TypeParser.getAbstractType rejects PseudoUtf8Type (an internal placeholder type) when it is requested after daemon setup has completed. This ConfigurationException exists because PseudoUtf8Type is reserved for internal functionality (vector search plumbing) and must never appear in user-visible schema.

Source

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

        try
        {
            Field field = typeClass.getDeclaredField("instance");
            return (AbstractType<?>) field.get(null);
        }
        catch (NoSuchFieldException | IllegalAccessException e)
        {
            // Trying with empty parser
            return getRawAbstractType(typeClass, EMPTY_PARSER);
        }
    }

    private static AbstractType<?> getAbstractType(String compareWith, TypeParser parser) throws SyntaxException, ConfigurationException
    {
        Class<? extends AbstractType<?>> typeClass = getAbstractTypeClass(compareWith);
        if (PseudoUtf8Type.class.isAssignableFrom(typeClass))
        {
            if (StorageService.instance.isDaemonSetupCompleted())
                throw new ConfigurationException(typeClass.getName() + " is reserved for internal functionality");
        }
        try
        {
            Method method = typeClass.getDeclaredMethod("getInstance", TypeParser.class);
            return (AbstractType<?>) method.invoke(null, parser);
        }
        catch (NoSuchMethodException | IllegalAccessException e)
        {
            // Trying to see if we have an instance field and apply the default parameter to it
            AbstractType<?> type = getRawAbstractType(typeClass);
            return AbstractType.parseDefaultParameters(type, parser);
        }
        catch (InvocationTargetException e)
        {
            ConfigurationException ex = new ConfigurationException("Invalid definition for comparator " + typeClass.getName() + ".");
            ex.initCause(e.getTargetException());
            throw ex;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove PseudoUtf8Type from the type string and use a supported comparator such as UTF8Type or AsciiType
2. If the name came from tooling output, treat it as internal-only and map it to the user-facing equivalent type
3. Upgrade/review any custom code that enumerates AbstractType classes by reflection and skips internal types
4. If seen during startup of a node with corrupted schema, repair the schema from a healthy node before full daemon setup completes

Example fix

// before
CREATE TABLE t (k text PRIMARY KEY, v frozen<PseudoUtf8Type>);
// after
CREATE TABLE t (k text PRIMARY KEY, v text);

static void rejectInternalTypes(String typeString) {
    if (typeString != null && typeString.contains("PseudoUtf8Type"))
        throw new IllegalArgumentException("PseudoUtf8Type is internal-only; use UTF8Type");
}

static boolean isUserFacingType(String typeName) {
    return typeName != null && !typeName.startsWith("PseudoUtf8");
}

try {
    AbstractType<?> t = TypeParser.parse(typeString);
} catch (ConfigurationException e) {
    if (e.getMessage().contains("reserved for internal functionality"))
        throw new SchemaConfigurationException("Internal type used in schema; substitute a user-facing comparator", e);
    throw e;
}

When it happens

Trigger: Parsing a type string naming PseudoUtf8Type (or a subclass) via TypeParser.parse/getAbstractType after StorageService daemon setup completed — e.g. user-supplied comparator "PseudoUtf8Type" in a CREATE TABLE or a hand-written type string referencing it.

Common situations: Users copying internal type names out of debug output or system logs into schema definitions, tooling that serializes internal comparators back to strings and feeds them into TypeParser, or attempting to reuse internal types for custom columns.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid comparator class %s: must define a public static ins
• 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/47af992376b459dc. Report an issue: GitHub.