{"record":{"id":"0b324d4dcb99a935","repo":"apache/cassandra","slug":"min-index-interval-of-is-too-low-for-expecte","errorCode":null,"errorMessage":"min_index_interval of {} is too low for {} expected keys of avg size {}; using interval of {} instead","messagePattern":"min_index_interval of (.+?) is too low for (.+?) expected keys of avg size (.+?); using interval of (.+?) instead","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/io/sstable/indexsummary/IndexSummaryBuilder.java","lineNumber":120,"sourceCode":"     * @param minIndexInterval - the minimum interval between entries selected for sampling\n     * @param samplingLevel - the level at which entries are sampled\n     */\n    public IndexSummaryBuilder(long expectedKeys, int minIndexInterval, int samplingLevel)\n    {\n        this.samplingLevel = samplingLevel;\n        this.startPoints = Downsampling.getStartPoints(BASE_SAMPLING_LEVEL, samplingLevel);\n\n        long expectedEntrySize = getEntrySize(defaultExpectedKeySize);\n        long maxExpectedEntries = expectedKeys / minIndexInterval;\n        long maxExpectedEntriesSize = maxExpectedEntries * expectedEntrySize;\n        if (maxExpectedEntriesSize > maxEntriesSize)\n        {\n            // that's a _lot_ of keys, and a very low min index interval\n            int effectiveMinInterval = (int) Math.ceil((double)(expectedKeys * expectedEntrySize) / maxEntriesSize);\n            maxExpectedEntries = expectedKeys / effectiveMinInterval;\n            maxExpectedEntriesSize = maxExpectedEntries * expectedEntrySize;\n            assert maxExpectedEntriesSize <= maxEntriesSize : maxExpectedEntriesSize;\n            logger.warn(\"min_index_interval of {} is too low for {} expected keys of avg size {}; using interval of {} instead\",\n                        minIndexInterval, expectedKeys, defaultExpectedKeySize, effectiveMinInterval);\n            this.minIndexInterval = effectiveMinInterval;\n        }\n        else\n        {\n            this.minIndexInterval = minIndexInterval;\n        }\n\n        // for initializing data structures, adjust our estimates based on the sampling level\n        maxExpectedEntries = Math.max(1, (maxExpectedEntries * samplingLevel) / BASE_SAMPLING_LEVEL);\n        offsets = new SafeMemoryWriter(4 * maxExpectedEntries).order(ByteOrder.LITTLE_ENDIAN);\n        entries = new SafeMemoryWriter(expectedEntrySize * maxExpectedEntries).order(ByteOrder.LITTLE_ENDIAN);\n\n        // the summary will always contain the first index entry (downsampling will never remove it)\n        nextSamplePosition = 0;\n        indexIntervalMatches++;\n    }\n","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/indexsummary/IndexSummaryBuilder.java#L102-L138","documentation":"IndexSummaryBuilder validates that the configured min_index_interval can hold the expected number of index summary entries within the fixed memory budget (maxEntriesSize). If expectedKeys * avgEntrySize exceeds the budget at that interval, it computes a larger effective interval, logs this warning, and silently overrides the configured min_index_interval so the builder's internal invariants hold.","triggerScenarios":"Creating an IndexSummaryBuilder with a very small min_index_interval (e.g. 1-8) combined with a very large expected key count (huge sstables), so that min_index_interval * maxEntriesSize cannot accommodate expectedKeys entries of the default expected key size.","commonSituations":"Very large tables/partitions (billions of keys) with aggressively tuned `min_index_interval` in cassandra.yaml or table options; users lowering min_index_interval to improve read latency without raising index summary memory (`index_summary_capacity_in_mb`).","solutions":["Raise `min_index_interval` for the table (ALTER TABLE ... WITH min_index_interval = 64 or higher) to match the key volume.","Increase index summary capacity (`nodetool setindexcapacity` / index_summary_capacity_in_mb) so the smaller interval fits.","Accept the warning: Cassandra automatically uses the larger effective interval; read latency may be slightly higher.","Reduce expected keys per sstable by compacting with larger target sstable sizes or splitting the table."],"exampleFix":"// before: cqlsh\nALTER TABLE ks.tbl WITH min_index_interval = 8;   -- too low for huge table\n// after\nALTER TABLE ks.tbl WITH min_index_interval = 256;","handlingStrategy":"validation","validationCode":"// Sanity-check interval vs table scale before setting\nlong expectedKeys = ...;               // rough upper bound of keys per sstable\nint minIndexInterval = 128;\n// rule of thumb: expectedKeys / minIndexInterval entries * ~entrySize must fit\n// within index_summary_capacity_in_mb; raise the interval or capacity if not.\nif ((expectedKeys / minIndexInterval) * 48 > indexSummaryCapacityBytes) {\n    minIndexInterval = 256; // or raise capacity\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Match min_index_interval to table size: keep the default 128 unless you have measured reasons otherwise.","Budget index summary memory via index_summary_capacity_in_mb when lowering intervals.","Check logs after ALTER TABLE / compaction for this warning — it means your interval was overridden.","For very large tables, prefer larger intervals and bigger sstables over tiny intervals."],"tags":["cassandra","index-summary","configuration","memory"],"backgroundTag":"invalid-config-value","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"}