Intervals.atLeast accepts a count of 0, then searches that evaluate it throw NullPointerException

Intervals.atLeast(minShouldMatch, sources...) checks only two special counts: equal to the number of sources (rewritten to unordered) and larger (a source that matches nothing). A count of 0 with one or more sources, passed directly or typed as fn:atLeast(0 a b) into the flexible StandardQueryParser, therefore builds a MinimumShouldMatchIntervalsSource whose queue of active sources has capacity 0. On the first candidate document its nextInterval() loop test proximityQueue.size() == minShouldMatch is true on the empty queue and proximityQueue.top().start() throws NullPointerException; on a segment that holds none of the source terms the iterator, built anyway, throws ArrayIndexOutOfBoundsException from its empty document queue. So count, top-k and sorted search, Weight#matches and explain fail wherever they evaluate it, with an internal exception instead of an argument error when the query is built. A negative count fails late with IllegalArgumentException from PriorityQueue. Default IndexWriterConfig and searcher, one document, assertions on or off; every release from 8.0.0 (query text from 9.1.0) to 10.6.0 and main. Nothing else is affected: no wrong hits, no hang, no result cached for the broken query, nothing written.

• Interval: a [start, end] range of token positions in one field of one document; Intervals.term("a") gives one per occurrence of a.
• Intervals.atLeast(minShouldMatch, sources...): "Return intervals that span combinations of intervals from minShouldMatch of the sources" (Intervals.java:563-565). Query text: fn:atLeast(min sources...), where min is "an integer specifying minimum number of sub-interval arguments that must match" (intervalfn/package-info.java:231).
• Proximity queue: the iterator keeps the minShouldMatch sub-iterators it is combining right now in a priority queue of that capacity, and the rest in a background queue (MinimumShouldMatchIntervalsSource.java:146-156, :186-195).

1. No lower bound. The factory handles minShouldMatch == sources.length (returns unordered(sources), Intervals.java:567-569) and minShouldMatch > sources.length (returns a NoMatchIntervalsSource, :570-576); any smaller count, 0 and negatives included, becomes new MinimumShouldMatchIntervalsSource(sources, minShouldMatch) (:577). Its constructor only does assert minShouldMatch < sources.length (MinimumShouldMatchIntervalsSource.java:46), which 0 satisfies. (With no sources at all, 0 is the == case and goes to unordered().)
2. An iterator is always built. intervals() returns null only if (iterators.size() < minShouldMatch) (:60), never true for 0 (:51-64).
3. A queue that holds nothing. The proximity queue is created with capacity minShouldMatch (:186-190); for capacity 0 PriorityQueue allocates a 2-slot heap whose top() returns heap[1], always null (PriorityQueue.java:117-119, :246-251). reset() moves minShouldMatch sub-iterators into it (MinimumShouldMatchIntervalsSource.java:279-288): none.
4. The NPE. nextInterval() begins while (this.proximityQueue.size() == minShouldMatch && proximityQueue.top().start() == start) (:217-218): 0 == 0, and top() is null. The scorer's two-phase check calls it on the first candidate document (IntervalScorer.java:80-81), so count, search and explain throw there; Weight#matches reaches the same loop through MinimumShouldMatchIntervalsSource.matches, which builds its own iterator and calls nextInterval() (:80-88).
5. No source term in the segment. Then the iterator has no sub-iterators; its DisiPriorityQueue (the intervals package's own copy) has length 0 (MinimumShouldMatchIntervalsSource.java:175), and the bulk scorer's first docID() reads heap[0] (DisiPriorityQueue.java:56-58): ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0.
6. Negative counts reach PriorityQueue's check "maxSize must be >= 0" (PriorityQueue.java:121-124), but only when the iterator is created at search time (by the scorer, or by matches for Weight#matches).
7. Query text. StandardSyntaxParser.jj:411-422 reads <NUMBER> (no sign: digits with an optional fraction, :160) and returns new AtLeast(parseInt(minShouldMatch), sources); AtLeast.toIntervalSource passes the number unchanged to Intervals.atLeast (intervalfn/AtLeast.java:38-44). So 0 can be typed; a negative cannot (fn:atLeast(-1 a b) is a ParseException).

Inside a Boolean OR, a non-scoring count may never ask the atLeast clause once another clause has matched: c OR fn:atLeast(0 a b) counted 1 on "a b c", but top-k search, index-order sorted search, explain and Weight#matches on the same query threw the NPE. Over an empty index there is no segment to evaluate it on, and count returns 0.

• Who is exposed. (a) Code that passes a computed or forwarded count to Intervals.atLeast. (b) Applications that hand end-user text to the flexible StandardQueryParser with interval functions (9.1.0 and later; the node calls Intervals.atLeast unchanged, intervalfn/AtLeast.java:38-44). The maintainers foresaw (b) for a sibling case: "I realize the query itself is malformed but such corner cases will happen if intervals are available from the query parser" (Dawid Weiss, on #10783 / LUCENE-9744).
• Downstream (read, not run). Solr's intervals query parser (apache/solr#4582, SOLR-13764) was released in Solr 10.1.0 (2026-10-27, built on Lucene 10.4.0, which has the same atLeast code) and is also on Solr main. Its at_least rule rejects only min_should_match < 0 and passes 0 to Intervals.atLeast, and the parser is registered by default. Elasticsearch and OpenSearch do not expose atLeast. That says nothing about private code.
• Default or opt-in. atLeast is an opt-in operator of a package that calls itself experimental (intervals/package-info.java:21). Nothing else is needed: the default IndexWriterConfig and searcher, assertions on or off. Only the seeded test codecs were run; the failing code is in the query's own iterator, not in the codec, so other codecs should behave the same (read, not run).
• Scale. One document; deterministic.
• What you see. An unchecked NullPointerException (or ArrayIndexOutOfBoundsException) from count, top-k and sorted search, Weight#matches and explain, where an argument error was due when the query was built. An application that maps IllegalArgumentException to a "bad request" reports an internal error instead; how a downstream reports it is up to it.
• What does not happen (executed probe): no wrong or extra hits (189 of 189 calls threw, with the clause in MUST, FILTER, MUST_NOT, constant-score and parsed positions on four searchers, including concurrent and always-caching ones), no hang, no result cached for the broken query (a repeat on an always-caching searcher threw again), the index untouched.
• Likelihood: rare. A constant 0 fails loudly on the first search, so testing catches it; it takes a computed, forwarded or typed 0, and atLeast is a less-used operator.

Put the file in the queries module's org.apache.lucene.queries.intervals test package and run the command. It uses new IndexWriterConfig() and a ByteBuffersDirectory, and calls only public API (Intervals, IntervalQuery, IndexSearcher). It asserts no hit count, so it accepts either fix: an IllegalArgumentException when the source is built (the test returns) or a search that runs (the test passes).

Under the test framework the default codec is randomized per seed (DEADBEEF picks Asserting(Lucene104)); the failing code does not depend on the codec, and seeds DEADBEEF and 5EED1234 fail the same way. The query-text path, fn:atLeast(0 a b) through StandardQueryParser, ends in the same Intervals.atLeast call and was left out on purpose; it fails the same way (executed).

Before using it as the regression test in a PR, rename the unused catch parameter e (catch (IllegalArgumentException e), line 43) to _: Lucene's ecj lint treats an unused exception parameter as an error, so ./gradlew :lucene:queries:check fails on the file as is. With _ (Lucene's own idiom, e.g. FSDirectory.java:230) the check passes with either fix, and the test still fails on main and passes with the fix (executed).

# main 645d4fe14a20, ./gradlew :lucene:queries:test --tests ...TestIntervalsAtLeastZero -Ptests.seed=DEADBEEF -Ptests.asserts=true
# (-Ptests.asserts=false: the same failure); middle stack frames elided
TestIntervalsAtLeastZero > testMinShouldMatchZero FAILED
    java.lang.AssertionError: expected atLeast(0, a, b) to be rejected or to search, got java.lang.NullPointerException: Cannot invoke "org.apache.lucene.queries.intervals.IntervalIterator.start()" because the return value of "org.apache.lucene.util.PriorityQueue.top()" is null
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:5DDA7A9C86BE18FD]:0)
        at org.apache.lucene.queries.intervals.TestIntervalsAtLeastZero.testMinShouldMatchZero(TestIntervalsAtLeastZero.java:49)

        Caused by:
        java.lang.NullPointerException: Cannot invoke "org.apache.lucene.queries.intervals.IntervalIterator.start()" because the return value of "org.apache.lucene.util.PriorityQueue.top()" is null
            at org.apache.lucene.queries.intervals.MinimumShouldMatchIntervalsSource$MinimumShouldMatchIntervalIterator.nextInterval(MinimumShouldMatchIntervalsSource.java:218)
            at org.apache.lucene.queries.intervals.IntervalScorer$1.matches(IntervalScorer.java:81)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.Weight$DefaultBulkScorer.scoreTwoPhaseIterator(Weight.java:311)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.Weight$DefaultBulkScorer.score(Weight.java:282)
            ...
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.IndexSearcher.count(IndexSearcher.java:528)
            at org.apache.lucene.queries.intervals.TestIntervalsAtLeastZero.testMinShouldMatchZero(TestIntervalsAtLeastZero.java:47)

:lucene:queries:test (FAILURE): 1 test, 1  failure

# with fix A: 1 test, passes (the 0 is rejected when the source is built); with fix B: passes (count runs)

• The contract. Intervals.atLeast: "Return intervals that span combinations of intervals from minShouldMatch of the sources" (Intervals.java:563-565), with no stated range and no @throws. Parser docs: fn:atLeast "Matches documents that contain at least the provided number of source intervals"; min is "an integer specifying minimum number of sub-interval arguments that must match" (intervalfn/package-info.java:223, :231). No document says 0 must throw either: rejecting it (fix A) or giving it a meaning (fix B) is the maintainers' choice; the bug is that accepted input later fails with an internal exception.
• Degenerate counts are normalised on purpose. The == and > shortcuts (Intervals.java:567-576) came from LUCENE-9744 (#10783, 8.8.2), "NPE on a degenerate query in MinimumShouldMatchIntervalsSource" (lucene/CHANGES.txt:5445-5446). Its fix was, in Alan Woodward's words, "a fix in the factory method that ensures we don't ever actually get a degenerate min-should-match interval". 0 is the case that fix did not cover.
• Validation elsewhere in the package. IntervalScoreFunction throws "pivot must be > 0" and "exp must be > 0" when built (IntervalScoreFunction.java:28, :35, :38).
• The same parser gives 0 a meaning elsewhere. Its Boolean min-should-match operator (a b)@0 parses and counts 1 on "a b c" (executed).
• Tests. No upstream test uses atLeast with 0 or a negative count; TestSimplifications.testMinShouldMatchSimplifications pins only the == and > rewrites (TestSimplifications.java:115-122).
• History. The missing bound and the loop guard date from the class's first commit (LUCENE-8622, 2019); the guard was only re-wrapped since (LUCENE-9570).

The strongest case for "intended" (built by the devil's advocate and reviews by an independent reviewer from another model family, OpenAI GPT-5.6, reading only): atLeast(0, ...) is meaningless, and the LUCENE-9744 reporter themselves called such a query "malformed"; the Intervals factories generally validate little (maxgaps(-1, ...) and extend(a, -1, 0) are accepted, unordered() with no sources throws a raw exception); MinimumShouldMatchIntervalsSource is package-private and its design comment assumes a count of at least 1; negative counts already end in an IllegalArgumentException.

Why it fails: the "malformed" LUCENE-9744 input was fixed anyway, for exactly the query-parser reason; the silently accepted numeric arguments return results, not exceptions, and the zero-source cases cannot be written as query text, while fn:atLeast(0 ...) can; the entry points are public and documented; and the negative value fails late and is not the headline. No checker rated the intended-behaviour argument better than weak. Verdict: not intended; a missing argument check.

Two fixes were run through gradle in a scratch worktree of 645d4fe14a20; both are one-file changes to Intervals.atLeast. The earlier checkers advised not to prescribe one: A is smaller and matches what LUCENE-9744 did for the other degenerate counts; B gives 0 the meaning BooleanQuery gives it. Until a fix ships, callers can check the count themselves.

The change is +3 lines in Intervals.java only (the finder's fix, re-made on 645d4fe14a20). One check at the entry point removes all three failures: the NPE, the AIOOBE and the late IllegalArgumentException for negative counts. It follows IntervalScoreFunction's convention and LUCENE-9744's "fix in the factory method".

public static IntervalsSource atLeast(int minShouldMatch, IntervalsSource... sources) {
  if (minShouldMatch < 1) {
    throw new IllegalArgumentException("minShouldMatch must be >= 1, got: " + minShouldMatch);
  }
  if (minShouldMatch == sources.length) {

Trade-offs

• A few queries that run today would fail when built. Searches with a count of 0 throw today wherever they evaluate it, but a search over an empty index (count 0), or a non-scoring count of a Boolean OR whose other clause already matched (c OR fn:atLeast(0 a b) counted 1 on "a b c"; top-k and sorted search, explain and Weight#matches on it threw), runs today. With fix A both throw when the query is built (executed).
• Query text. StandardQueryParser.parse("fn:atLeast(0 a b)", "f") then throws a bare IllegalArgumentException instead of a QueryNodeException (executed with the finder's identical fix); a parser-side check (option C) would make it a parse error.
• No sources. Intervals.atLeast(0) with no sources, which today fails through unordered() ("Cannot make a ConjunctionDISI of less than 2 iterators"), fails with this message instead.
• A @throws IllegalArgumentException line in the javadoc would document the bound.

What the checks validated

• Gradle, seed DEADBEEF, 645d4fe14a20: the repro passes with assertions on and off (and on the standalone runner).
• :lucene:queries:test in full: 513 tests in 52 suites (the repro included), 5 skipped, 0 failures; org.apache.lucene.queryparser.flexible.*: 161 tests in 14 suites, 1 skipped, 0 failures; the intervals tests with assertions off: 118 tests, 0 failures.
• :lucene:queries:check -x test (google-java-format, ecj lint, forbidden APIs) passes once the repro's catch parameter is renamed _ (see Minimal repro).

The change is +7 lines in Intervals.java only: reject negative counts, and for 0 with at least one source return or(sources), as BooleanQuery treats minimumNumberShouldMatch 0 and as the same parser treats (a b)@0.

if (minShouldMatch < 0) {
  throw new IllegalArgumentException("minShouldMatch must be >= 0, got: " + minShouldMatch);
}
if (minShouldMatch == 0 && sources.length > 0) {
  // like BooleanQuery's minimumNumberShouldMatch 0: no minimum, any one source matches
  return or(sources);
}

Trade-offs

Gives 0 a meaning, so the parser needs nothing. But it picks semantics the javadoc does not state: "at least 0 of the sources" read literally is met by any document, which or is not.

What the checks validated

• Gradle, seed DEADBEEF, 645d4fe14a20: the repro passes (the search runs) with assertions on and off (standalone runner); the intervals tests (118, 0 failures) and org.apache.lucene.queryparser.flexible.* (161, 1 skipped, 0 failures) pass with assertions on; :lucene:queries:check -x test passes. The whole queries module was not run with B.

Reject fn:atLeast(0 ...) as a parse error, for example in the IntervalAtLeast rule of StandardSyntaxParser.jj (the generated parser then has to be regenerated).

Trade-offs

Only changes the exception type seen by parser users; not run.

For example require size() > 0 in the loop guard of MinimumShouldMatchIntervalsSource.java:217.

Trade-offs

Does not even remove the NPE: with the loop skipped, the test size() < minShouldMatch at :228 (0 < 0) is false, and proximityQueue.top().start() at :233 dereferences null again. It also leaves the ArrayIndexOutOfBoundsException and the meaning of 0 undefined. Read, not run.

Method: non-formal (a degenerate-argument sweep; no model checker, SMT solver, prover or bounded-exhaustive harness produced the signal).

• A hunt unit (intervals builder and multi-term sources), 2026-10-26, on main ea57360912ed. While extending the unit's reference semantics to atLeast, the finder, an AI tool, wrote a probe that ran 15 degenerate calls of the Intervals factories against a small index: atLeast(0, a, b), atLeast(-1, a, b), atLeast(1, a), atLeast(0), atLeast(2) with no sources, extend(a, -1, 0), extend(a, 0, -1), maxgaps(-1, ...), maxwidth(-1, a), within(a, -1, b), notWithin(a, -2, b), and unordered(), ordered(), or(), phrase() with no sources.
• atLeast(0, a, b) was the call that was accepted and then threw NullPointerException at search time; atLeast(-1, a, b) failed late with IllegalArgumentException. The finder read the factory and the iterator, and wrote a deterministic public-API JUnit (direct API and parsed fn:atLeast(0 a b)) and a 3-line fix.
• Independent checkers then widened it: the ArrayIndexOutOfBoundsException on segments with none of the terms, Weight#matches, nested query text, and every release from 8.0.0.