apache/cassandra · error · InvalidRequestException

The order of columns in the CLUSTERING ORDER directive must

Error message

The order of columns in the CLUSTERING ORDER directive must match that of the clustering columns (%s must appear before %s)

What it means

The CLUSTERING ORDER BY directive must list clustering columns in the same relative order as they appear in the PRIMARY KEY. When iterating the declared order, if the directive names a column that comes later in the clustering sequence than the column expected at that position (and the expected column is itself present in the directive but out of place), Cassandra throws this error.

Source

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

            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)
        {
            validateCompactTable(clusteringColumnProperties, columns);
        }
        else
        {
            // Static columns only make sense if we have at least one clustering column. Otherwise everything is static anyway
            if (clusteringColumns.isEmpty() && !staticColumns.isEmpty())
                throw ire("Static columns are only useful (and thus allowed) if the table has at least one clustering column");
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Reorder the CLUSTERING ORDER BY entries to match the clustering column order in PRIMARY KEY.
Alternatively change the PRIMARY KEY so the clustering column order matches the desired CLUSTERING ORDER BY sequence.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// Ensure ORDER BY order is a subsequence-matching order of clustering columns:
List<String> clustering = List.of("c1", "c2");
List<String> order = List.of("c1", "c2");
if (!clustering.subList(0, order.size()).equals(order)) throw new IllegalArgumentException("CLUSTERING ORDER BY order must match PRIMARY KEY");

Try / catch

try { session.execute(ddl); } catch (com.datastax.driver.core.exceptions.InvalidQueryException e) { if (e.getMessage().contains("must match that of the clustering columns")) { /* reorder clause */ } else throw e; }

Prevention

Always author CLUSTERING ORDER BY in the same order as clustering columns in PRIMARY KEY.
When changing sort direction, reorder PRIMARY KEY columns if needed instead of reordering ORDER BY.
Use schema-migration tests that create every table in CI.

When it happens

Trigger: CREATE TABLE ... PRIMARY KEY (pk, c1, c2) WITH CLUSTERING ORDER BY (c2 DESC, c1 ASC) — c2 is ordered before c1 although c1 precedes c2 in the primary key.

Common situations: Reordering clustering columns for sort preference without reordering the PRIMARY KEY; adding a new clustering column in the middle and forgetting to update the ORDER BY clause.

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/fd765887010565fd. Report an issue: GitHub.