With beamWidth = 1 no HNSW graph can be built: the builder sizes a queue beamWidth / 2 = 0, and a merge closes the IndexWriter

The HNSW vector formats (Lucene99HnswVectorsFormat, and by code reading the scalar-quantized and bit-vector HNSW formats and two sandbox formats) accept any beamWidth from 1 to 3200, and HnswGraphBuilder rejects only beamWidth <= 0. Since 10.2.0 (#14331, "Speedup merging of HNSW graphs") every builder also allocates an extra candidate queue for merge-time level-0 searches, sized Math.min(beamWidth / 2, M * 3). For beamWidth = 1 that is 0, and the heap under the queue throws IllegalArgumentException: initialCapacity must be > 0 and < 2147483630; got: 0. So no HNSW graph can be built with a beam width of 1, for any maxConn and any data. From 10.4.0, segments below the tiny-segment threshold (648 vectors by default) still flush without a graph; then the first merge that has to build one throws, and IndexWriter treats it as a tragic event: the writer closes and everything added since the last commit is discarded. On the flush path the 648th vector document of a segment is rejected, and so is the next one, while the writer stays open. On 10.2.x and 10.3.x the first vector document already fails. 10.1.0 and earlier work; every release from 10.2.0 to 10.6.0 and main fail. The fix is one line, Math.max(1, ...).

• Accepted range. Lucene99HnswVectorsFormat.java:278-283: if (beamWidth <= 0 || beamWidth > MAXIMUM_BEAM_WIDTH) throws "beamWidth must be positive and less than or equal to 3200" (:112). The same check in Lucene104HnswScalarQuantizedVectorsFormat.java:171-173, HnswBitVectorsFormat.java:116-118 and the sandbox DedupHnswVectorsFormat.java:175-180 and DedupHnswScalarQuantizedVectorsFormat.java:189-194 (both write through Lucene99HnswVectorsWriter). HnswGraphBuilder.java:177-179: "beamWidth must be positive".
• Three queues. The base constructor (HnswGraphBuilder.java:166-196), which every other constructor and subclass reaches, allocates entryCandidates = new GraphBuilderKnnCollector(1) (:193), beamCandidates = new GraphBuilderKnnCollector(beamWidth) (:194) and beamCandidates0 = new GraphBuilderKnnCollector(Math.min(beamWidth / 2, M * 3)) (:195). GraphBuilderKnnCollector(int k) makes new NeighborQueue(k, false) (:821-822), which makes new TernaryLongHeap(initialSize) (NeighborQueue.java:59-60), which throws for initialCapacity < 1 (TernaryLongHeap.java:57-59).
• Only merges that reuse graphs use the third queue (:349-351, level == 0 && eps0 != null && eps0.size() > 0, called from MergingHnswGraphBuilder.java:229 and, on main, from the concurrent merge's HnswConcurrentMergeBuilder.java:602), but it is allocated in every builder, so all graph building fails: the merge without a source graph (IncrementalHnswGraphMerger.java:159-161, the repro), the flush (Lucene99HnswVectorsWriter.java:832-836 -> :809-814), the merge of segments with graphs (MergingHnswGraphBuilder.java:73; by code reading) and the concurrent merge workers (HnswConcurrentMergeBuilder.java:493, :519; by code reading).
• When a graph is needed. shouldCreateGraph(100, n) is n > (int) (ln(n) * 100) (Lucene99HnswVectorsWriter.java:716-722, HnswGraphSearcher.java:56-58, HNSW_GRAPH_THRESHOLD = 100 at Lucene99HnswVectorsFormat.java:137): false for 500 (621), true from 648 (647) and for 1,000 (690).
• Why the flush keeps failing. In addValue the exception comes from initializeGraphBuilder() (:835) before node++ (:841), so the next vector document meets the same condition and throws again (the next one was executed). "Rejected" is what addDocument reports: the field writer has already buffered the vector (flatFieldVectorsWriter.addValue, :832), and DocumentsWriterPerThread marks the failed document deleted (DocumentsWriterPerThread.java:302-307, :399).
• Why the writer closes. IndexWriter.merge catches the Throwable and calls tragicEvent(t, "merge") (IndexWriter.java:5109-5113), which closes the writer and rolls back uncommitted changes (tragicEvent -> maybeCloseOnTragicEvent -> rollbackInternal, :6090-6105). Only a failed merge does this; a flush-path failure leaves the writer open.
• Exhaustive check. Over all 1,638,400 accepted (maxConn, beamWidth) pairs (1..512 x 1..3200), 512 give a non-positive queue size, all with beamWidth = 1; with the fix, none.

• Who is hit. Lucene99HnswVectorsFormat(maxConn, 1) (executed); by code reading also Lucene104HnswScalarQuantizedVectorsFormat, HnswBitVectorsFormat and the sandbox DedupHnswVectorsFormat / DedupHnswScalarQuantizedVectorsFormat, which accept the same range. Any maxConn, any data, any similarity.
• What goes wrong (10.4.0 and later). Small segments flush; the first merge, forced or natural, whose result needs a graph throws, and the writer closes as a tragic event, which rolls it back: every document added since the last commit is lost (all 1,000 in the repro, which never commits; executed: afterwards the directory holds no index). A flush of 648 or more vectors rejects the threshold-crossing document and the next one at addDocument, while the writer stays open.
• 10.2.x and 10.3.x build the flush graph eagerly, so the first vector addDocument already throws (LongHeap "maxSize must be > 0 ... got: 0").
• Upgrades. An index written with beamWidth = 1 on 10.1.0 or earlier keeps working on 10.2.0 or later only until its first graph build: a merge that needs a graph, or a new vector document (on 10.2.x-10.3.x the first one, from 10.4.0 the one that takes a segment to 648 vectors). By code reading: beamWidth is not stored in the index.
• What was not seen. Every executed failure is a loud exception; no silent corruption, hang or wrong search result was observed in the executed tests, and the last commit stayed readable (the independent reproduction's probe: 800 committed documents in 2 segments after the failed merge).
• Workaround. Use beamWidth >= 2; 2 passes on main, 10.6.0 and 10.1.0.
• How likely. Rare: upstream randomized tests draw beam widths from 5 or more (HnswGraphTestCase nextInt(10) + 5, RandomCodec 10 to 50), and the recorded searches found no report in the five affected release lines; whoever sets 1 hits it on the first graph build.

Copy the test into lucene/core/src/test/org/apache/lucene/codecs/lucene99/ of a Lucene checkout and run the command below; it uses public Lucene APIs plus Lucene's test framework (LuceneTestCase, newDirectory(), TestUtil.alwaysKnnVectorsFormat) and no package-private member. The vectors, the codec and the merge scheduler are fixed by the test; newDirectory() returns a randomised directory, and LuceneTestCase also randomises the similarity, the locale and the timezone. It failed under seed DEADBEEF with assertions on and off and under seed CAFEBABE with assertions off. The 500/500 split matters: each flushed segment stays below the 648-vector graph threshold, so the failure shows at the merge, where it closes the writer.

This is the hunt's minimal test with its one comment line rewritten to fit the 100-column format check; the code is unchanged. It passes :lucene:core:checkGoogleJavaFormat; the original 127-column comment did not. With assertions on and off it fails on main and passes with the fix, under gradle and the standalone runner; on the standalone runner it fails on 10.6.0 and passes on 10.1.0.

The test checks only that forceMerge(1) does not throw; an upstream regression test may also assert one segment and a kNN hit, as the graph-merge probe under Suggested fixes does. The registration check, the credibility audit and the diagram use another, unpublished copy of the same test: the field is named "vector", two lines carry comments, and it ends with assertTrue(w.isOpen()), which on main is never reached because forceMerge throws. It fails and passes the same way.

cp $REPRO/TestHnswBeamWidthOneMerge.java $LUCENE/lucene/core/src/test/org/apache/lucene/codecs/lucene99/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.codecs.lucene99.TestHnswBeamWidthOneMerge -Ptests.seed=DEADBEEF -Ptests.asserts=true
# and once more with -Ptests.asserts=false: it fails both ways

# gradle, fresh worktree at main 645d4fe14a20, -Ptests.seed=DEADBEEF -Ptests.asserts=true (the same with false)
TestHnswBeamWidthOneMerge > testForceMergeWithBeamWidthOne FAILED
    java.lang.IllegalArgumentException: initialCapacity must be > 0 and < 2147483630; got: 0
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:D330CEFBEFE7284]:0)
        at org.apache.lucene.util.TernaryLongHeap.<init>(TernaryLongHeap.java:59)
        at org.apache.lucene.util.hnsw.NeighborQueue.<init>(NeighborQueue.java:60)
        at org.apache.lucene.util.hnsw.HnswGraphBuilder$GraphBuilderKnnCollector.<init>(HnswGraphBuilder.java:822)
        at org.apache.lucene.util.hnsw.HnswGraphBuilder.<init>(HnswGraphBuilder.java:195)
        at org.apache.lucene.util.hnsw.HnswGraphBuilder.<init>(HnswGraphBuilder.java:147)
        at org.apache.lucene.util.hnsw.HnswGraphBuilder.<init>(HnswGraphBuilder.java:141)
        at org.apache.lucene.util.hnsw.HnswGraphBuilder.create(HnswGraphBuilder.java:123)
        at org.apache.lucene.util.hnsw.IncrementalHnswGraphMerger.createBuilder(IncrementalHnswGraphMerger.java:160)
        at org.apache.lucene.util.hnsw.IncrementalHnswGraphMerger.merge(IncrementalHnswGraphMerger.java:255)
        at org.apache.lucene.codecs.lucene99.Lucene99HnswVectorsWriter.buildAndWriteGraph(Lucene99HnswVectorsWriter.java:525)
        ...
        at org.apache.lucene.index.IndexWriter.merge(IndexWriter.java:5081)
        ...
        at org.apache.lucene.index.IndexWriter.forceMerge(IndexWriter.java:2229)
1 test completed, 1 failed

# standalone runner, the same test (tests_run=1 failures=1 each, seed DEADBEEF)
main 645d4fe14a20                   -ea and -da   the same exception at HnswGraphBuilder.<init>:195
10.6.0 / 10.5.2 / 10.4.0            -da           the same, at :216 / :215 / :190
10.3.2 / 10.2.0                     -da           at the first addDocument: maxSize must be > 0 and < 2147483630; got: 0 (LongHeap), :165
10.1.0                              -ea and -da   passes

# tragic close with the default ConcurrentMergeScheduler (an independent probe on main, -da; 2 committed 400-vector segments)
PROBE bw=2 forceMerge ok / isOpen=true tragic=null / committed docs=800 segs=1
PROBE bw=1 forceMerge threw java.io.IOException: background merge hit exception: ... cause=java.lang.IllegalArgumentException: initialCapacity must be > 0 and < 2147483630; got: 0
PROBE bw=1 isOpen=false tragic=java.lang.IllegalArgumentException: initialCapacity must be > 0 and < 2147483630; got: 0
PROBE bw=1 committed docs=800 segs=2
PROBE addDoc failed at doc 647: java.lang.IllegalArgumentException: initialCapacity must be > 0 ...   (0-based: the 648th)
PROBE addDoc isOpen=true tragic=null
PROBE next addDoc: java.lang.IllegalArgumentException: initialCapacity must be > 0 ...

• Contract. The format javadoc calls beamWidth "the size of the queue maintained during graph construction" (Lucene99HnswVectorsFormat.java:191), the builder javadoc "the size of the beam search to use when finding nearest neighbors" (HnswGraphBuilder.java:133, :161). Nothing documents a minimum of 2 or says that half the beam sizes another queue; the merge builder's javadoc describes the merge-time level-0 search as "We also limit beamWidth (efConstruction to M*3)" (MergingHnswGraphBuilder.java:47-49), a cap, which for beamWidth = 1 would be 1, not 0.
• Tests. TestLucene99HnswVectorsFormat.testLimits rejects beamWidth 0, -1 and 3201 only (:64-74); HnswGraphTestCase.testHnswGraphBuilderInvalid says // beamWidth must be > 0 (:888-890).
• History. Inside the #14331 PR branch, commit 09735cf80a1 ("Adjust beamCandidates0", 2025-03-18) replaced Math.min(beamWidth, M * 2) with Math.min(beamWidth / 2, M * 3); the discussion covers only the cap (M * 2 to M * 3). The builder's beamWidth <= 0 check dates from 2020: it was added by 09f78e2927c (LUCENE-9610); git blame shows e1cd426bce39 (LUCENE-9644), which moved it.
• A beam width below maxConn has been called valid. In #13752 (2024, closed as not planned) Michael McCandless asked whether beamWidth < maxConn should throw; Ben Trent answered "It is a weird configuration for sure, but I am not sure its invalid", and no validation was added.
• A sibling edge case in the same merger was fixed as a bug: #14407 / #14420 (an empty join-set heap, fixed in 10.2.0).

The case (built by the intended-behaviour devil's advocate and the cross-model reviews, all rating it weak): a beam of one gives a poor graph and nobody should run it in production; the formats are @lucene.experimental (Lucene99HnswVectorsFormat.java:83); a maintainer may prefer to reject beamWidth < 2.

Why it fails: the documented and tested rule is "positive", the value worked through 10.1.0, and today's failure is an opaque internal error that closes the writer at merge time, not a clear validation. @lucene.experimental allows API changes, not crashes on accepted input. Rejecting beamWidth < 2 is one of the fixes (option B), and it still changes code. The argument bears on priority (Low), not on whether it is a bug.

The hunt's no-noise rule does not claim behaviour that "needs absurd parameters and then fails loudly". This bug does fail loudly, and 1 is an unusual value: that is the main argument for Low priority, and it is conceded. It is still claimed because the value is inside the documented and tested contract ("positive"), it worked through 10.1.0 (a regression), and the failure does not come where the value is set: it comes later, at the first graph build, often at a merge, where it closes the writer and rolls back uncommitted documents. The cross-model fact check reached the same call: claim, Low.

Three options; A was validated with gradle in a fresh scratch worktree at 645d4fe14a20, B and C were not executed. A maintainer may prefer B, a clear early rejection; either resolves the bug. Not a fix: allocating beamCandidates0 lazily, only when the eps0 path needs it. Flushes and graph-free merges would work, but the merge of two segments that have graphs would still hit the zero size.

HnswGraphBuilder.java:195 becomes beamCandidates0 = new GraphBuilderKnnCollector(Math.max(1, Math.min(beamWidth / 2, M * 3)));.

beamCandidates0 = new GraphBuilderKnnCollector(Math.max(1, Math.min(beamWidth / 2, M * 3)));
// was: new GraphBuilderKnnCollector(Math.min(beamWidth / 2, M * 3))

Trade-offs

• No change for beamWidth >= 2: there min(beamWidth / 2, M * 3) is already at least 1 (M >= 1), so every graph built today is built the same way.
• For beamWidth = 1 the level-0 merge search keeps 1 candidate, the same as the main beam queue.
• Keeps the documented "positive" contract, and beamWidth = 1 works again as it did up to 10.1.0.

What the checks validated

Gradle in a fresh scratch worktree at 645d4fe14a20 (JDK 25.0.3, -Ptests.seed=DEADBEEF), 2026-10-30:

• without the fix the minimal test fails with -Ptests.asserts=true and false; git apply of the one-line diff succeeds, and with it the test passes both ways; after git apply -R it fails again;
• the closest suites pass with the fix: org.apache.lucene.util.hnsw.*, org.apache.lucene.codecs.lucene99.*, org.apache.lucene.codecs.lucene104.* and TestKnnGraph = 26 suites, 526 tests, 18 skipped, 0 failures (54 of them postings, segment-info and packing tests, and 1 the minimal test; among them TestHnswFloatVectorGraph 32, TestHnswByteVectorGraph 26, TestLucene99HnswVectorsFormat 60, TestLucene104HnswScalarQuantizedVectorsFormat 64); TestHnswBitVectorsFormat in lucene/codecs: 8 tests, 0 failures;
• :lucene:core:checkGoogleJavaFormat passes with the fix and the test;
• the graph-merge path, which by code reading uses the clamped queue (MergingHnswGraphBuilder.java:229 passes each smaller-graph node's known neighbours as eps0; the probe does not instrument the queue): a probe (not the repro) with two flushed 1,000-vector segments that each get a graph, then forceMerge(1), passes with the fix (-ea, -da): the HNSW info stream reports "build graph from merging 2 graphs of 2000 vectors, graph sizes:1000 1000", the merged index has 1 segment and 2,000 documents, and a k = 5 kNN query returns 5 hits;
• earlier: the hunt's shadow-fix runs pass the test on main and on 10.2.0, and an independent reviewer from another model family ran the upstream format-limit, builder-invalid-input and graph read/write tests with the fix: pass.

In Lucene99HnswVectorsFormat, Lucene104HnswScalarQuantizedVectorsFormat, HnswBitVectorsFormat and HnswGraphBuilder. Not executed.

Trade-offs

Fails fast at codec construction instead of at a merge, but changes the documented "positive" contract and the testLimits / testHnswGraphBuilderInvalid expectations, rejects configurations that worked through 10.1.0, and must be repeated in every format with the same check (the sandbox dedup formats have it too).

Not executed. Never 0 either.

Trade-offs

Changes the queue size for every odd beamWidth below 6 * M (3 -> 2, 5 -> 3, ...), so merge-built graphs change for those settings; option A changes nothing outside beamWidth = 1.

Method: code reading during model building, then executed tests and an exhaustive check (the hunt's non-formal tier: the bug was seen in the code, not reported by a model checker).

• First signal (2026-10-25). A unit modelling the HNSW graph format derived the legal parameter domain from the format's validation (1 <= beamWidth <= 3200) and checked that every buffer sized from maxConn and beamWidth is legal on it; beamWidth / 2 is not. It confirmed this with an executed probe and a JUnit on the stock main jars. In the same minute a unit modelling merge-time graph reuse noticed the line while modelling the eps0 path, and its bounded-exhaustive harness reported the builder exception for beamWidth = 1 at every M and for no other beam width.
• Hunt. An adjudication-take-over unit re-ran the earliest repro on main (-ea, -da: fails), reduced it to one JUnit test with no package-private member, checked the three queue sizes over all 1,638,400 accepted (maxConn, beamWidth) pairs (512 non-positive, all at beamWidth = 1; 0 with the fix) and wrote the one-line fix.
• Checks. An independent reproducer, an intended-behaviour devil's advocate, two executed reviews by an independent reviewer from another model family (OpenAI GPT-5.6), an adjudication, a credibility audit and a no-noise gate confirmed it; the version-history runs ran the release matrix.