apache/cassandra · error · InvalidRequestException

Some clustering keys are missing: %s

Error message

Some clustering keys are missing: %s

What it means

For statement types that don't allow clustering column slices (e.g. certain key-based writes/reads), clustering keys must be fully specified. If clustering key components are left unrestricted, processClusteringColumnsRestrictions throws this error listing the missing keys.

Source

Thrown at src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java:674

     * Processes the clustering column restrictions.
     *
     * @param hasQueriableIndex <code>true</code> if some of the queried data are indexed, <code>false</code> otherwise
     * @param selectsOnlyStaticColumns <code>true</code> if the selected or modified columns are all statics,
     * <code>false</code> otherwise.
     */
    private void processClusteringColumnsRestrictions(boolean hasQueriableIndex,
                                                      boolean selectsOnlyStaticColumns,
                                                      boolean forView,
                                                      boolean allowFiltering)
    {
        checkFalse(!type.allowClusteringColumnSlices() && clusteringColumnsRestrictions.hasSlice(),
                   "Slice restrictions are not supported on the clustering columns in %s statements", type);

        if (!type.allowClusteringColumnSlices()
            && (!table.isCompactTable() || (table.isCompactTable() && !hasClusteringColumnsRestrictions())))
        {
            if (!selectsOnlyStaticColumns && hasUnrestrictedClusteringColumns())
                throw invalidRequest("Some clustering keys are missing: %s",
                                     Joiner.on(", ").join(getUnrestrictedClusteringColumns()));
        }
        else
        {
            if (clusteringColumnsRestrictions.needsFilteringOrIndexing() && !hasQueriableIndex && !allowFiltering)
                throw invalidRequest("Clustering column restrictions require the use of secondary indices" +
                                     " or filtering for map-element restrictions and for the following operators: %s",
                                     Operator.operatorsRequiringFilteringOrIndexingFor(ColumnMetadata.Kind.CLUSTERING)
                                             .stream()
                                             .map(Operator::toString)
                                             .collect(Collectors.joining(", ")));

            if (hasClusteringColumnsRestrictions() && clusteringColumnsRestrictions.needFiltering())
            {
                if (hasQueriableIndex || forView)
                {
                    usesSecondaryIndexing = true;
                }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Restrict all clustering columns up to the last one you need: WHERE pk = ... AND c1 = ... AND c2 = ...
2. Use SELECT (which allows clustering ranges) instead of the restrictive statement type
3. Delete a full partition only if the table has no clustering columns, or specify full primary key per row
4. Model data so the primary key matches the granularity you query/delete at

Example fix

// before
DELETE FROM orders WHERE customer_id = 'c1';  -- clustering key order_id missing
// after
DELETE FROM orders WHERE customer_id = 'c1' AND order_id = 'o1';

// Ensure all clustering key columns up to the needed prefix are restricted:
for (ColumnMetadata c : table.getClusteringColumns()) {
  if (!whereColumns.contains(c.getName()) && !allowsRange) throw new IllegalArgumentException("Missing clustering key: " + c.getName());
}

When it happens

Trigger: DELETE FROM t WHERE pk = 'a' when the table has clustering columns that aren't restricted; SELECT on a table with clustering keys supplying only the partition key in a statement type that forbids ranges.

Common situations: Deleting a whole partition without knowing clustering keys (use a range instead where allowed); table schema evolved to add clustering columns while queries stayed the same; compact-table semantics confusion.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• PRIMARY KEY column "%s" cannot be restricted as preceding co
• Cannot create ENTRIES index on frozen map clustering column
• category %s not found in %s
• GRANT operation is not supported by AllowAllAuthorizer
• REVOKE operation is not supported by AllowAllAuthorizer

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