apache/cassandra · error · InvalidRequestException

Indexes cannot be both included and excluded:

Error message

Indexes cannot be both included and excluded:

What it means

InvalidRequestException from IndexHints.fromCQLNames when one or more indexes appear in both the included and excluded sets. Such hints are contradictory, so the request is rejected, listing the conflicting index names.

Source

Thrown at src/java/org/apache/cassandra/db/filter/IndexHints.java:394

                                          IndexRegistry indexRegistry)
    {
        if (included != null && included.size() > maxIncludedOrExcludedIndexCount())
            throw new InvalidRequestException(TOO_MANY_INDEXES_ERROR + included.size());

        if (excluded != null && excluded.size() > maxIncludedOrExcludedIndexCount())
            throw new InvalidRequestException(TOO_MANY_INDEXES_ERROR + excluded.size());

        IndexHints hints = IndexHints.create(fetchIndexes(included, table, indexRegistry),
                                             fetchIndexes(excluded, table, indexRegistry));

        if (hints == IndexHints.NONE)
            return hints;

        // Ensure that no index is both included and excluded
        Set<IndexMetadata> conflictingIndexes = Sets.intersection(hints.included, hints.excluded);
        if (!conflictingIndexes.isEmpty())
        {
            throw new InvalidRequestException(CONFLICTING_INDEXES_ERROR + IndexMetadata.joinNames(conflictingIndexes));
        }

        // Ensure that all nodes in the cluster are in a version that supports index hints, including this one
        Set<InetAddressAndPort> badNodes = MessagingService.instance().endpointsWithConnectionsOnVersionBelow(MessagingService.VERSION_60);
        if (MessagingService.current_version < MessagingService.VERSION_60)
            badNodes.add(FBUtilities.getBroadcastAddressAndPort());
        if (!badNodes.isEmpty())
            throw new InvalidRequestException("Index hints are not supported in clusters below 14.");

        return hints;
    }

    private static int maxIncludedOrExcludedIndexCount()
    {
        int guardrail = DatabaseDescriptor.getSecondaryIndexesPerTableFailThreshold();

        // If no guardrail is configured, use a value that safely fits in a single byte for serialization:
        return guardrail > 0 ? guardrail : 128;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove the conflicting index from either the included or excluded set
  2. Pre-filter intersection of include/exclude names in client code before issuing the query
  3. Decide which behavior is intended for that index and keep only one hint

Example fix

// before
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a) EXCLUDE INDEXES (idx_a)
// after
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a)
Defensive patterns

Strategy: validation

Validate before calling

Set<String> conflict = Sets.intersection(includedNames, excludedNames); if (!conflict.isEmpty()) throw new IllegalArgumentException("Conflicting hints: " + conflict);

Try / catch

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("both included and excluded")) fixHintListsAndRetry(); }

Prevention

When it happens

Trigger: A query that includes and excludes the same qualified index name — e.g. hint construction code merging user-provided include/exclude lists that overlap.

Common situations: Client-side query builders concatenating hints from different sources; user typos; scripts adding exclusions without checking existing includes.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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