apache/cassandra · error · ConfigurationException

Index kind is null for index ${name}

Error message

Index kind is null for index ${name}

What it means

IndexMetadata.validate requires a non-null kind; every index must declare how it is implemented (e.g. Keys/Composites/CUSTOM). A null kind means the metadata was constructed incompletely or deserialized incorrectly.

Source

Thrown at src/java/org/apache/cassandra/schema/IndexMetadata.java:140

    public static String generateDefaultIndexName(String table, ColumnIdentifier column)
    {
        return PATTERN_NON_WORD_CHAR.matcher(table + '_' + column.toString() + "_idx").replaceAll("");
    }

    public static String generateDefaultIndexName(String table)
    {
        return PATTERN_NON_WORD_CHAR.matcher(table + "_idx").replaceAll("");
    }

    public void validate(TableMetadata table)
    {
        // TODO: address validating the length by CASSANDRA-20445
        if (!isValidCharsName(name))
            throw new ConfigurationException("Illegal index name " + name);

        if (kind == null)
            throw new ConfigurationException("Index kind is null for index " + name);

        if (kind == Kind.CUSTOM)
        {
            if (options == null || !options.containsKey(IndexTarget.CUSTOM_INDEX_OPTION_NAME))
                throw new ConfigurationException(String.format("Required option missing for index %s : %s",
                                                               name, IndexTarget.CUSTOM_INDEX_OPTION_NAME));

            // Get the fully qualified class name:
            String className = getIndexClassName();

            Class<? extends Index> indexerClass = FBUtilities.classForNameWithoutInitialization(className, "custom indexer", Index.class);
            validateCustomIndexOptions(table, indexerClass, options);
        }
    }

    public String getIndexClassName()
    {
        if (isCustom())

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set the index kind explicitly (IndexMetadata.Kind.KEYS/COMPOSITES/CUSTOM) when constructing metadata
2. Use IndexMetadata.raw/fromIndexTargets factory methods that derive the kind automatically
3. Repair system_schema.indexes rows if they were corrupted by external editing

Example fix

// before
IndexMetadata.builder().name("idx").target("col").build() // kind unset
// after
IndexMetadata.raw("idx", IndexTarget.fromTarget("col"), TableMetadata.Kind.KEYS, Collections.emptyMap())

if (index.getKind() == null) throw new IllegalArgumentException("index kind must be set before validating " + index.name);

try { index.validate(table); } catch (ConfigurationException e) { log.error("index kind missing for " + index.name, e); }

When it happens

Trigger: Building an IndexMetadata (e.g. via builder or deserialization) without setting kind, then calling validate(TableMetadata); exercised by testRejectsNonCustomIndexWithoutInitializing paths.

Common situations: Custom schema-management tooling constructing IndexMetadata manually and forgetting kind; corrupted/badly migrated system_schema rows where the kind column is null.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Cannot specify options for a non-CUSTOM index
• Cannot set %s to empty string
• cannot be used in comparisons, so cannot be used as a cluste
• comparator #%s '%s' in '%s' didn't validate
• Configuration for at least one datacenter must be present

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