apache/cassandra · error · InvalidRequestException

Index hints are not supported in clusters below 14.

Error message

Index hints are not supported in clusters below 14.

What it means

InvalidRequestException thrown when index hints are used while some cluster nodes (or the coordinator itself) run a version below the one that supports index hints (14 / VERSION_60 wire compatibility). Mixed-version clusters cannot propagate hints safely, so the operation is rejected.

Source

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

        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;
    }

    private static Set<IndexMetadata> fetchIndexes(Set<QualifiedName> indexNames, TableMetadata table, IndexRegistry indexRegistry)
    {
        if (indexNames == null || indexNames.isEmpty())
            return Collections.emptySet();

        Set<IndexMetadata> indexes = new HashSet<>(indexNames.size());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Upgrade all nodes to Cassandra 4.2+ (version supporting index hints) and finish the rolling upgrade
2. Check nodetool version / endpointsWithConnectionsOnVersionBelow to find lagging nodes
3. Retry the query without index hints until the cluster is fully upgraded

Example fix

// before
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a) on mixed-version cluster
// after
-- after upgrading every node to >= 14:
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a)

boolean clusterSupportsHints = MessagingService.instance().endpointsWithConnectionsOnVersionBelow(MessagingService.VERSION_60).isEmpty() && MessagingService.current_version >= MessagingService.VERSION_60;

try { session.execute(hintedStmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("below 14")) session.execute(stripHints(hintedStmt)); }

When it happens

Trigger: Running a hinted query on a cluster that is mid-upgrade or has any node with messaging connections below VERSION_60, including when the local coordinator version is itself too old.

Common situations: Rolling upgrades where a hinted query hits an old node; forgotten nodes left on Cassandra 3.x/4.x; development clusters mixing versions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot DROP COMPACT STORAGE as some nodes in the cluster (%s
• It's not possible to use all the specified included indexes
• Cannot have more than 'secondary_indexes_per_table_fail_thre
• Indexes cannot be both included and excluded:
• Prepare phase failed because it encountered legacy sstables

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