{"record":{"id":"6653419ea00b9caf","repo":"apache/cassandra","slug":"clustering-block-upper-bits-those-not-associated","errorCode":null,"errorMessage":"Clustering block upper bits (those not associated with keys) expected to be 0:${clusteringBlockHeader}","messagePattern":"Clustering block upper bits \\(those not associated with keys\\) expected to be 0:(.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/sstable/SSTableCursorReader.java","lineNumber":1056,"sourceCode":"            //    varint clustering_block_header;\n            //    simple_cell[] clustering_cells;\n            // };\n            if (clusteringIndex % 32 == 0)\n            {\n                fixedLengthClusteringLength = flushFixedLengthRun(dataReader, clustering, fixedLengthClusteringLength);\n                clusteringBlockHeader = dataReader.readUnsignedVInt();\n                clustering.writeUnsignedVInt(clusteringBlockHeader);\n            }\n\n            // load value if present\n            if ((clusteringBlockHeader & 0b11) == 0)\n                fixedLengthClusteringLength = readClusteringValue(dataReader, clustering, types[clusteringIndex], fixedLengthClusteringLength);\n\n            clusteringBlockHeader = clusteringBlockHeader >>> 2;\n        }\n        flushFixedLengthRun(dataReader, clustering, fixedLengthClusteringLength);\n        if (clusteringBlockHeader != 0) {\n            throw new IOException(\"Clustering block upper bits (those not associated with keys) expected to be 0:\" + clusteringBlockHeader);\n        }\n    }\n\n    /**\n     * Copies the pending run of fixed-length components in one read. They are adjacent on disk, so\n     * the run is only broken by a variable-length component or by a block boundary.\n     *\n     * @return the new pending run length, always 0\n     */\n    private static int flushFixedLengthRun(RandomAccessReader dataReader, ResizableByteBuffer clustering, int fixedLengthClusteringLength) throws IOException\n    {\n        if (fixedLengthClusteringLength != 0)\n            clustering.loadPart(dataReader, fixedLengthClusteringLength);\n        return 0;\n    }\n\n    /**\n     * Reads one present clustering component. A fixed-length component joins the pending run; a","sourceCodeStart":1038,"sourceCodeEnd":1074,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/SSTableCursorReader.java#L1038-L1074","documentation":"While deserializing clustering values, SSTableCursorReader consumes a bit-per-key clustering block header. After shifting through all keys, the remaining upper bits must be zero; nonzero residual bits mean the header encodes keys not covered by the schema, so the data is treated as corrupt and an IOException is thrown.","triggerScenarios":"Reading a row whose clustering block header has bits set beyond the number of clustering columns/types known from the schema — schema mismatch (table altered) or corrupted bytes.","commonSituations":"Reading sstables written under an incompatible schema; nodes with stale schema (missed schema changes); bit-flip disk corruption.","solutions":["Run nodetool verify on the sstable; scrub if corrupt.","Ensure schema agreement across the cluster (nodetool describecluster) and propagate schema changes.","Restore the sstable from backup or rebuild via nodetool repair if corruption is confirmed.","Confirm the sstable was not copied from a table with a different clustering definition."],"exampleFix":"// before\nRow row = cursor.readRow(); // raw IOException\n// after\ntry {\n    Row row = cursor.readRow();\n} catch (IOException e) {\n    throw new CorruptSSTableException(e, ssTableReader.getFilename());\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    row = cursor.readRow();\n} catch (IOException e) {\n    throw new CorruptSSTableException(e, filename); // caller triggers scrub\n}","preventionTips":["Keep schema in agreement across nodes before serving reads of old sstables.","Run verify/scrub after suspected disk issues.","Do not move sstables between tables with different clustering schemas.","Check schema hashes (nodetool describecluster) when this error appears cluster-wide."],"tags":["sstable","corruption","deserialization","schema"],"backgroundTag":"schema-validation-failed","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"}