apache/cassandra · error · InvalidRequestException

Only clustering key columns can be defined in CLUSTERING ORD

Error message

Only clustering key columns can be defined in CLUSTERING ORDER directive: %s are not clustering columns

What it means

During CREATE TABLE, Cassandra validates that every column named in the CLUSTERING ORDER BY directive is actually one of the table's clustering columns. The builder collects identifiers in clusteringOrder that are absent from clusteringColumns and throws this InvalidRequest if any remain. This prevents a clustering order definition referencing columns that have no clustering semantics.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateTableStatement.java:342

        partitionKeyColumns.forEach(column ->
        {
            ColumnProperties columnProperties = columns.remove(column);
            partitionKeyColumnProperties.add(columnProperties);
        });

        clusteringColumns.forEach(column ->
        {
            ColumnProperties columnProperties = columns.remove(column);
            boolean reverse = !clusteringOrder.getOrDefault(column, true);
            clusteringColumnProperties.add(reverse ? columnProperties.withReversedType() : columnProperties);
        });

        List<ColumnIdentifier> nonClusterColumn = clusteringOrder.keySet().stream()
                                                                 .filter((id) -> !clusteringColumns.contains(id))
                                                                 .collect(Collectors.toList());
        if (!nonClusterColumn.isEmpty())
        {
            throw ire("Only clustering key columns can be defined in CLUSTERING ORDER directive: " + nonClusterColumn + " are not clustering columns");
        }

        int n = 0;
        for (ColumnIdentifier id : clusteringOrder.keySet())
        {
            ColumnIdentifier c = clusteringColumns.get(n);
            if (!id.equals(c))
            {
                if (clusteringOrder.containsKey(c))
                    throw ire("The order of columns in the CLUSTERING ORDER directive must match that of the clustering columns (%s must appear before %s)", c, id);
                else
                    throw ire("Missing CLUSTERING ORDER for column %s", c);
            }
            ++n;
        }

        // For COMPACT STORAGE, we reject any "feature" that we wouldn't be able to translate back to thrift.
        if (useCompactStorage)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Move the named column into the clustering portion of the PRIMARY KEY (after the partition key).
Remove the column from the CLUSTERING ORDER BY clause so it only lists clustering columns.
Fix the column name typo in CLUSTERING ORDER BY so it matches an actual clustering column.

Example fix

// before
CREATE TABLE t (pk int, c1 int, v text, PRIMARY KEY (pk)) WITH CLUSTERING ORDER BY (c1 DESC);
// after
CREATE TABLE t (pk int, c1 int, v text, PRIMARY KEY (pk, c1)) WITH CLUSTERING ORDER BY (c1 DESC);

Defensive patterns

Strategy: validation

Validate before calling

// Parse the PRIMARY KEY clustering columns and the CLUSTERING ORDER BY list; before executing:
Set<String> clustering = Set.of("c1"); // from PRIMARY KEY (pk, c1)
List<String> orderCols = List.of("c1"); // parsed from CLUSTERING ORDER BY
if (!clustering.containsAll(orderCols)) throw new IllegalArgumentException("CLUSTERING ORDER BY names non-clustering columns");

Try / catch

try { session.execute(ddl); } catch (com.datastax.driver.core.exceptions.InvalidQueryException e) { if (e.getMessage().contains("CLUSTERING ORDER")) { /* fix schema DDL */ } else throw e; }

Prevention

Keep CLUSTERING ORDER BY limited to columns appearing after the partition key in PRIMARY KEY.
Generate CLUSTERING ORDER BY from the same list used to build the PRIMARY KEY.
Lint DDL scripts to cross-check ORDER BY columns against clustering columns.

When it happens

Trigger: CREATE TABLE with WITH CLUSTERING ORDER BY (some_col ASC/DESC) where some_col is a regular, static, or partition-key column rather than a clustering column.

Common situations: Typos in the column name inside CLUSTERING ORDER BY; moving a column from clustering to partition key in a refactor; assuming a PRIMARY KEY column listed first can be ordered.

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

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