apache/cassandra · error · InvalidRequestException

allowFilteringMessage(state)

Error message

allowFilteringMessage(state)

What it means

When the partition key restrictions require filtering (e.g. partial prefix or non-EQ on a key component) and ALLOW FILTERING was not specified, the statement is rejected with the dynamic allowFilteringMessage(state) text. Such queries would require an unbounded full scan, so Cassandra demands explicit opt-in (or a queriable secondary index, or being a view definition).

Source

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

            if (partitionKeyRestrictions.isOnToken())
                isKeyRange = true;

            if (partitionKeyRestrictions.isEmpty() && partitionKeyRestrictions.hasUnrestrictedPartitionKeyComponents())
            {
                isKeyRange = true;
                usesSecondaryIndexing = hasQueriableIndex;
            }

            // If there is a queriable index, no special condition is required on the other restrictions.
            // But we still need to know 2 things:
            // - If we don't have a queriable index, is the query ok
            // - Is it queriable without 2ndary index, which is always more efficient
            // If a component of the partition key is restricted by a relation, all preceding
            // components must have a EQ. Only the last partition key component can be in IN relation.
            if (partitionKeyRestrictions.needFiltering())
            {
                if (!allowFiltering && !forView && !hasQueriableIndex && requiresAllowFilteringIfNotSpecified(table, true))
                    throw new InvalidRequestException(allowFilteringMessage(state));

                isKeyRange = true;
                usesSecondaryIndexing = hasQueriableIndex;
            }
        }
    }

    public boolean hasPartitionKeyRestrictions()
    {
        return !partitionKeyRestrictions.isEmpty();
    }

    /**
     * Checks if the restrictions contain any non-primary key restrictions
     * @return <code>true</code> if the restrictions contain any non-primary key restrictions, <code>false</code> otherwise.
     */
    public boolean hasNonPrimaryKeyRestrictions()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add ALLOW FILTERING to the statement (accepting the performance cost).
2. Restrict the full partition key with EQ (and IN on the last component only) so filtering is unnecessary.
3. Create/use a secondary index on the filtered column so hasQueriableIndex becomes true.
4. Redesign the table so the query matches the partition key layout.

Example fix

// before
SELECT * FROM sensor_data WHERE device_id > 100;
// after
SELECT * FROM sensor_data WHERE device_id = 123; // or
SELECT * FROM sensor_data WHERE device_id > 100 ALLOW FILTERING;

if (!isFullPartitionKeyEquality(whereClause) && !allowFilteringRequested)
    throw new IllegalArgumentException("this query needs ALLOW FILTERING or a full partition key");

try { session.execute(stmt); }
catch (InvalidRequestException e) {
    if (e.getMessage().toLowerCase().contains("allow filtering")) { /* retry with ALLOW FILTERING or fix the predicate */ }
    else throw e;
}

When it happens

Trigger: A SELECT whose partition key restrictions need filtering (needFiltering() true), with allowFiltering == false, not for a view, no queriable index on the restricted columns, and the table requires allow-filtering unless specified.

Common situations: Queries like 'WHERE pk > x' or restricted only on the second component of a composite partition key without ALLOW FILTERING; common when porting SQL habits or after key schema changes.

Related errors

• Key may not be empty
• Key length of %d is longer than maximum of %d
• Must specify full partition key bounds for the underlying ta
• Some partition key parts are missing: %s
• Cannot add new field %s of type %s to user type %s as the ty

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