apache/cassandra · error · InvalidRequestException

GROUP BY functions accept only one clustering column as…

Error message

GROUP BY functions accept only one clustering column as parameter, got: %s

What it means

SelectStatement's GROUP BY validation rejects group-by functions (like tok(...) or bucket-style selectors) that take more than one clustering column as parameter. Functions in GROUP BY must operate on exactly one clustering column so the grouping maps onto partition-row ordering.

Solutions

Pass exactly one clustering column to the function in GROUP BY
If you need multi-column grouping, use plain GROUP BY col1, col2 without a function
For token-based grouping, group by a single column or restructure the query

Example fix

// before
SELECT bucket(a, b) FROM ks.t GROUP BY bucket(a, b); -- two clustering columns
// after
SELECT bucket(a) FROM ks.t GROUP BY bucket(a); -- one clustering column

Defensive patterns

Strategy: validation

Validate before calling

// client-side check before issuing the query
if (groupByFuncArgs.size() != 1) throw new IllegalArgumentException("GROUP BY functions accept exactly one clustering column");

Try / catch

try { session.execute(query); }
catch (InvalidRequestException e) { if (e.getMessage().contains("GROUP BY functions")) { /* rewrite query without function or with one arg */ } }

Prevention

Use plain GROUP BY col1, col2 for multi-column grouping
Restrict GROUP BY function usage to a single clustering column

When it happens

Trigger: Executing a SELECT with `GROUP BY somefunc(colA, colB)` where the function selector contributes more than one clustering column to the selector factory's `columns` list.

Common situations: Writing tok(pk1, pk2) style calls with multiple arguments in GROUP BY, or user-defined/wrapped selectors accepting several clustering columns; usually a misunderstanding that GROUP BY functions are limited to a single clustering column.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/statements/SelectStatement.java:1599

            Iterator<ColumnMetadata> pkColumns = metadata.primaryKeyColumns().iterator();
            List<ColumnMetadata> columns = null;
            Selector.Factory selectorFactory = null;
            for (Selectable.Raw raw : parameters.groups)
            {
                Selectable selectable = raw.prepare(metadata);
                ColumnMetadata def = null;

                // For GROUP BY we only allow column names or functions at the higher level.
                if (selectable instanceof WithFunction)
                {
                    WithFunction withFunction = (WithFunction) selectable;
                    validateGroupByFunction(withFunction);
                    columns = new ArrayList<ColumnMetadata>();
                    selectorFactory = selectable.newSelectorFactory(metadata, null, columns, boundNames);
                    checkFalse(columns.isEmpty(), "GROUP BY functions must have one clustering column name as parameter");
                    if (columns.size() > 1)
                        throw invalidRequest("GROUP BY functions accept only one clustering column as parameter, got: %s",
                                             columns.stream().map(c -> c.name.toCQLString()).collect(Collectors.joining(",")));

                    def = columns.get(0);
                    checkTrue(def.isClusteringColumn(),
                              "Group by functions are only supported on clustering columns, got %s", def.name);
                }
                else
                {
                    def = (ColumnMetadata) selectable;
                    checkTrue(def.isPartitionKey() || def.isClusteringColumn(),
                              "Group by is currently only supported on the columns of the PRIMARY KEY, got %s", def.name);
                    checkNull(selectorFactory, "Functions are only supported on the last element of the GROUP BY clause");
                }

                while (true)
                {
                    checkTrue(pkColumns.hasNext(),
                              "Group by currently only support groups of columns following their declared order in the PRIMARY KEY");

View on GitHub (pinned to 88fd0f6a0e)