apache/cassandra · error · IllegalArgumentException

Invalid lookback distribution; max value is

Error message

Invalid lookback distribution; max value is ${maxValue}, but series only ranges from ${writeCount} to ${start+totalCount}

What it means

LookbackReadGenerator validates at construction that the lookback distribution's maximum value does not exceed the number of keys that will exist in the series (start + totalCount). A lookback larger than the written range would read keys that are never written, so the constructor throws IllegalArgumentException naming the distribution max and the actual series range.

Solutions

1. Increase the series size (-n) so it is at least as large as the lookback distribution's max
2. Reduce the lookback distribution max, e.g. lookback=uniform(1..50000) when n=50000
3. Populate the keyspace with a write run first so start+totalCount covers the lookback range

Example fix

// before
stress read n=1000 lookback=uniform(1..5000)
// after
stress read n=5000 lookback=uniform(1..5000)

if (lookback.maxValue() > seriesStart + seriesTotalCount)
    throw new IllegalArgumentException("lookback max " + lookback.maxValue() + " exceeds series range");

boolean lookbackFits(Distribution lookback, long start, long totalCount) { return lookback.maxValue() <= start + totalCount; }

try { new LookbackReadGenerator(lookback); } catch (IllegalArgumentException e) { log.error("Adjust -n or lookback: {}", e.getMessage()); }

When it happens

Trigger: cassandra-stress read command where the lookback distribution's max (e.g. lookback=uniform(1..100000)) exceeds start+totalCount for the configured series size (e.g. n=50000 with start=0).

Common situations: Running reads against a stress series smaller than the lookback window; forgetting that lookback is relative to total keys written; running read-only stress without a prior population run of enough rows.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• sample range is invalid
• CAS is supported only for type 'samerow'
• File '' doesn't exist!
• Illegal distribution specification:
• Illegal distribution type:

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

Appendix: source

Thrown at tools/stress/src/org/apache/cassandra/stress/generate/SeedManager.java:237

                    return;
                if (head.getKey().seed == min + 1 && this.writeCount.compareAndSet(min, min + 1))
                {
                    afterMin.remove(head.getKey());
                    continue;
                }
                return;
            }
        }

        private class LookbackReadGenerator extends Generator
        {
            final Distribution lookback;

            public LookbackReadGenerator(Distribution lookback)
            {
                this.lookback = lookback;
                if (lookback.maxValue() > start + totalCount)
                    throw new IllegalArgumentException("Invalid lookback distribution; max value is " + lookback.maxValue()
                                                       + ", but series only ranges from " + writeCount + " to " + (start + totalCount));
            }

            public Seed next(int visits)
            {
                long lookback = this.lookback.next();
                long range = writeCount.get();
                long startOffset = range - lookback;
                if (startOffset < 0)
                {
                    if (range == totalCount && !wrap)
                        return null;
                    startOffset = range == 0 ? 0 : lookback % range;
                }
                return new Seed(start + startOffset, visits);
            }
        }

View on GitHub (pinned to 88fd0f6a0e)