{"record":{"id":"9c9f9672a32eb341","repo":"apache/cassandra","slug":"index-hints-are-not-supported-in-clusters-below-14","errorCode":null,"errorMessage":"Index hints are not supported in clusters below 14.","messagePattern":"Index hints are not supported in clusters below 14\\.","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/filter/IndexHints.java","lineNumber":402,"sourceCode":"        IndexHints hints = IndexHints.create(fetchIndexes(included, table, indexRegistry),\n                                             fetchIndexes(excluded, table, indexRegistry));\n\n        if (hints == IndexHints.NONE)\n            return hints;\n\n        // Ensure that no index is both included and excluded\n        Set<IndexMetadata> conflictingIndexes = Sets.intersection(hints.included, hints.excluded);\n        if (!conflictingIndexes.isEmpty())\n        {\n            throw new InvalidRequestException(CONFLICTING_INDEXES_ERROR + IndexMetadata.joinNames(conflictingIndexes));\n        }\n\n        // Ensure that all nodes in the cluster are in a version that supports index hints, including this one\n        Set<InetAddressAndPort> badNodes = MessagingService.instance().endpointsWithConnectionsOnVersionBelow(MessagingService.VERSION_60);\n        if (MessagingService.current_version < MessagingService.VERSION_60)\n            badNodes.add(FBUtilities.getBroadcastAddressAndPort());\n        if (!badNodes.isEmpty())\n            throw new InvalidRequestException(\"Index hints are not supported in clusters below 14.\");\n\n        return hints;\n    }\n\n    private static int maxIncludedOrExcludedIndexCount()\n    {\n        int guardrail = DatabaseDescriptor.getSecondaryIndexesPerTableFailThreshold();\n\n        // If no guardrail is configured, use a value that safely fits in a single byte for serialization:\n        return guardrail > 0 ? guardrail : 128;\n    }\n\n    private static Set<IndexMetadata> fetchIndexes(Set<QualifiedName> indexNames, TableMetadata table, IndexRegistry indexRegistry)\n    {\n        if (indexNames == null || indexNames.isEmpty())\n            return Collections.emptySet();\n\n        Set<IndexMetadata> indexes = new HashSet<>(indexNames.size());","sourceCodeStart":384,"sourceCodeEnd":420,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/filter/IndexHints.java#L384-L420","documentation":"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.","triggerScenarios":"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.","commonSituations":"Rolling upgrades where a hinted query hits an old node; forgotten nodes left on Cassandra 3.x/4.x; development clusters mixing versions.","solutions":["Upgrade all nodes to Cassandra 4.2+ (version supporting index hints) and finish the rolling upgrade","Check nodetool version / endpointsWithConnectionsOnVersionBelow to find lagging nodes","Retry the query without index hints until the cluster is fully upgraded"],"exampleFix":"// before\nSELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a) on mixed-version cluster\n// after\n-- after upgrading every node to >= 14:\nSELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (idx_a)","handlingStrategy":"validation","validationCode":"boolean clusterSupportsHints = MessagingService.instance().endpointsWithConnectionsOnVersionBelow(MessagingService.VERSION_60).isEmpty() && MessagingService.current_version >= MessagingService.VERSION_60;","typeGuard":null,"tryCatchPattern":"try { session.execute(hintedStmt); } catch (InvalidRequestException e) { if (e.getMessage().contains(\"below 14\")) session.execute(stripHints(hintedStmt)); }","preventionTips":["Complete rolling upgrades before enabling index hints","Gate hint usage on cluster version checks in client tooling","Monitor node versions and alert on stragglers"],"tags":["cassandra","index-hints","cluster-version","upgrade"],"backgroundTag":"unsupported-operation","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}