min_index_interval of {} is too low for {} expected keys of

Error message

min_index_interval of {} is too low for {} expected keys of avg size {}; using interval of {} instead

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/indexsummary/IndexSummaryBuilder.java:120

     * @param minIndexInterval - the minimum interval between entries selected for sampling
     * @param samplingLevel - the level at which entries are sampled
     */
    public IndexSummaryBuilder(long expectedKeys, int minIndexInterval, int samplingLevel)
    {
        this.samplingLevel = samplingLevel;
        this.startPoints = Downsampling.getStartPoints(BASE_SAMPLING_LEVEL, samplingLevel);

        long expectedEntrySize = getEntrySize(defaultExpectedKeySize);
        long maxExpectedEntries = expectedKeys / minIndexInterval;
        long maxExpectedEntriesSize = maxExpectedEntries * expectedEntrySize;
        if (maxExpectedEntriesSize > maxEntriesSize)
        {
            // that's a _lot_ of keys, and a very low min index interval
            int effectiveMinInterval = (int) Math.ceil((double)(expectedKeys * expectedEntrySize) / maxEntriesSize);
            maxExpectedEntries = expectedKeys / effectiveMinInterval;
            maxExpectedEntriesSize = maxExpectedEntries * expectedEntrySize;
            assert maxExpectedEntriesSize <= maxEntriesSize : maxExpectedEntriesSize;
            logger.warn("min_index_interval of {} is too low for {} expected keys of avg size {}; using interval of {} instead",
                        minIndexInterval, expectedKeys, defaultExpectedKeySize, effectiveMinInterval);
            this.minIndexInterval = effectiveMinInterval;
        }
        else
        {
            this.minIndexInterval = minIndexInterval;
        }

        // for initializing data structures, adjust our estimates based on the sampling level
        maxExpectedEntries = Math.max(1, (maxExpectedEntries * samplingLevel) / BASE_SAMPLING_LEVEL);
        offsets = new SafeMemoryWriter(4 * maxExpectedEntries).order(ByteOrder.LITTLE_ENDIAN);
        entries = new SafeMemoryWriter(expectedEntrySize * maxExpectedEntries).order(ByteOrder.LITTLE_ENDIAN);

        // the summary will always contain the first index entry (downsampling will never remove it)
        nextSamplePosition = 0;
        indexIntervalMatches++;
    }

View on GitHub (pinned to 88fd0f6a0e)

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.

Example fix

// before: cqlsh
ALTER TABLE ks.tbl WITH min_index_interval = 8;   -- too low for huge table
// after
ALTER TABLE ks.tbl WITH min_index_interval = 256;

Defensive patterns

Strategy: validation

Validate before calling

// Sanity-check interval vs table scale before setting
long expectedKeys = ...;               // rough upper bound of keys per sstable
int minIndexInterval = 128;
// rule of thumb: expectedKeys / minIndexInterval entries * ~entrySize must fit
// within index_summary_capacity_in_mb; raise the interval or capacity if not.
if ((expectedKeys / minIndexInterval) * 48 > indexSummaryCapacityBytes) {
    minIndexInterval = 256; // or raise capacity
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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`).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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