{"record":{"id":"fd765887010565fd","repo":"apache/cassandra","slug":"the-order-of-columns-in-the-clustering-order-direc","errorCode":null,"errorMessage":"The order of columns in the CLUSTERING ORDER directive must match that of the clustering columns (%s must appear before %s)","messagePattern":"The order of columns in the CLUSTERING ORDER directive must match that of the clustering columns \\((.+?) must appear before (.+?)\\)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/statements/schema/CreateTableStatement.java","lineNumber":352,"sourceCode":"            clusteringColumnProperties.add(reverse ? columnProperties.withReversedType() : columnProperties);\n        });\n\n        List<ColumnIdentifier> nonClusterColumn = clusteringOrder.keySet().stream()\n                                                                 .filter((id) -> !clusteringColumns.contains(id))\n                                                                 .collect(Collectors.toList());\n        if (!nonClusterColumn.isEmpty())\n        {\n            throw ire(\"Only clustering key columns can be defined in CLUSTERING ORDER directive: \" + nonClusterColumn + \" are not clustering columns\");\n        }\n\n        int n = 0;\n        for (ColumnIdentifier id : clusteringOrder.keySet())\n        {\n            ColumnIdentifier c = clusteringColumns.get(n);\n            if (!id.equals(c))\n            {\n                if (clusteringOrder.containsKey(c))\n                    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);\n                else\n                    throw ire(\"Missing CLUSTERING ORDER for column %s\", c);\n            }\n            ++n;\n        }\n\n        // For COMPACT STORAGE, we reject any \"feature\" that we wouldn't be able to translate back to thrift.\n        if (useCompactStorage)\n        {\n            validateCompactTable(clusteringColumnProperties, columns);\n        }\n        else\n        {\n            // Static columns only make sense if we have at least one clustering column. Otherwise everything is static anyway\n            if (clusteringColumns.isEmpty() && !staticColumns.isEmpty())\n                throw ire(\"Static columns are only useful (and thus allowed) if the table has at least one clustering column\");\n        }\n","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/statements/schema/CreateTableStatement.java#L334-L370","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nCREATE TABLE t (pk int, c1 int, c2 int, PRIMARY KEY (pk, c1, c2)) WITH CLUSTERING ORDER BY (c2 DESC, c1 ASC);\n// after\nCREATE TABLE t (pk int, c1 int, c2 int, PRIMARY KEY (pk, c1, c2)) WITH CLUSTERING ORDER BY (c1 ASC, c2 DESC);","handlingStrategy":"validation","validationCode":"// Ensure ORDER BY order is a subsequence-matching order of clustering columns:\nList<String> clustering = List.of(\"c1\", \"c2\");\nList<String> order = List.of(\"c1\", \"c2\");\nif (!clustering.subList(0, order.size()).equals(order)) throw new IllegalArgumentException(\"CLUSTERING ORDER BY order must match PRIMARY KEY\");","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["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."],"tags":["cql","schema","create-table","clustering-order"],"backgroundTag":"schema-validation-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}