apache/cassandra · error · ConfigurationException

Duplicate index name

Error message

Duplicate index name %s in keyspace %s

What it means

Thrown from KeyspaceMetadata.validate when two or more tables within the same keyspace contain indexes with the same name. Cassandra requires index names to be unique keyspace-wide, so schema announcements (announceNewKeyspace/announceKeyspaceUpdate) fail with a ConfigurationException.

Solutions

1. Rename one of the indexes so names are unique within the keyspace (e.g. prefix with table name: tbl1_col_idx).
2. Find the offenders: SELECT keyspace_name, table_name, index_name FROM system_schema.indexes WHERE keyspace_name='ks' and look for duplicated names.
3. If generated programmatically, make your naming scheme include the table name to guarantee uniqueness.

Example fix

// before
CREATE INDEX idx_user ON ks.users (email);
CREATE INDEX idx_user ON ks.orders (user_email); // duplicate in ks
// after
CREATE INDEX users_email_idx ON ks.users (email);
CREATE INDEX orders_user_email_idx ON ks.orders (user_email);

Set<String> seen = new HashSet<>();
for (String idx : allIndexNamesInKeyspace("ks")) if (!seen.add(idx)) throw new IllegalStateException("Duplicate index name: " + idx);

try { keyspaceMetadata.validate(); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Duplicate index name")) renameIndexAndRetry(); else throw e; }

When it happens

Trigger: Creating a schema (loading a snapshot schema, applying a DDL script, or programmatic schema construction) where two tables in keyspace K each define an index named 'idx_x'; validate iterates all tables' indexes and detects the duplicate before announcing the keyspace.

Common situations: Hand-written CQL migration scripts reusing a name like 'idx_name' across tables, programmatic schema builders generating default index names, restoring a hand-edited schema file, ORMs that name indexes per-entity without keyspace scoping.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• ACCESS TO DATACENTERS operations not supported by…
• ALREADY_EXISTS
• Already exists
• An error occurred while scrubbing the partition with key
• Because of this name

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

Appendix: source

Thrown at src/java/org/apache/cassandra/schema/KeyspaceMetadata.java:423

        StringBuilder result = new StringBuilder(cqlString);
        SchemaDescriptionsUtil.appendCommentOnKeyspace(result, this);
        SchemaDescriptionsUtil.appendSecurityLabelOnKeyspace(result, this);
        return result.toString();
    }

    public void validate(ClusterMetadata metadata)
    {
        validateKeyspaceName(name, ConfigurationException::new);
        params.validate(name, null, metadata);
        tablesAndViews().forEach(TableMetadata::validate);

        Set<String> indexNames = new HashSet<>();
        for (TableMetadata table : tables)
        {
            for (IndexMetadata index : table.indexes)
            {
                if (indexNames.contains(index.name))
                    throw new ConfigurationException(format("Duplicate index name %s in keyspace %s", index.name, name));

                indexNames.add(index.name);
            }
        }
    }

    static Optional<KeyspaceDiff> diff(KeyspaceMetadata before, KeyspaceMetadata after)
    {
        return KeyspaceDiff.diff(before, after);
    }

    public static final class KeyspaceDiff
    {
        public final KeyspaceMetadata before;
        public final KeyspaceMetadata after;

        public final TablesDiff tables;
        public final ViewsDiff views;

View on GitHub (pinned to 88fd0f6a0e)