ConcurrentQueryLoader's javadoc example uses QueryError and a (Monitor, List) constructor that no Lucene release has had

ConcurrentQueryLoader (lucene-monitor) registers many queries with a Monitor on several threads, "to speed up startup times for a Monitor". Its class javadoc says "Use as follows:" and shows six lines: List<QueryError> errors = new ArrayList<>();, then try (ConcurrentQueryLoader loader = new ConcurrentQueryLoader(monitor, errors)) { for (MonitorQuery mq : getQueries()) { loader.add(mq); } }. Lucene has no QueryError type, and the class has only the constructors (Monitor) and (Monitor, int, int). Copied into a project with monitor and getQueries() supplied, the example fails with cannot find symbol: class QueryError; with QueryError replaced by a real type, javac reports no suitable constructor found for ConcurrentQueryLoader(Monitor,List<...>). Load errors are not collected in a caller's list either: the loader keeps the IOExceptions that Monitor.register throws in its threads, and close() normally rethrows them as suppressed exceptions of one IOException (unchecked exceptions are not collected). The two lines are the API of Luwak, the project the module was ported from; a commit on the port branch removed QueryError and the list constructors in April 2019 and left the example as it was. Written as new ConcurrentQueryLoader(monitor) without the list, the example compiles, and that is the form Lucene's own TestConcurrentQueryLoader uses. It has been broken in every release that has the module, 8.2.0 to 10.6.0, and on main. Nothing in Lucene behaves wrongly; only the example is stale.

• Constructors: ConcurrentQueryLoader(Monitor monitor) (line 70), which uses one thread per available processor and a queue of DEFAULT_QUEUE_SIZE = 2000 (lines 63, 71), and ConcurrentQueryLoader(Monitor monitor, int threads, int queueSize) (line 81). Nothing else.
• Errors: a private List<IOException> errors (line 61). A worker adds an IOException thrown by monitor.register(...) (lines 141, 144-145); close() normally waits for the workers (if the closing thread is interrupted, it stops waiting, lines 110-114) and then throws one new IOException with every collected one as a suppressed exception (lines 115-118). Only IOExceptions are collected: an unchecked exception from register ends its worker and close() does not report it.
• On main, QueryError occurs in lucene/ only on line 43 and in an unrelated test method name (TestHighlightingMatcher.testQueryErrors); no commit on any ref of the Lucene history ever added such a class (only the never-merged port PR's branch, in the author's fork, had one). A bytecode scan of every build with the class (8.2.0 to 10.5.2, and main) finds no QueryError and only the two constructors.

Javadoc does not compile <pre> blocks, and the example has no {@link} that javadoc would check. Lucene's only test of the class, TestConcurrentQueryLoader.testLoading, uses new ConcurrentQueryLoader(monitor) and loads 200 queries (2000 nightly).

Any runtime defect; the free example names monitor and getQueries() (normal for a fragment). Side observation: line 51, "The Monitor's MonitorQueryParser must be thread-safe for this to work correctly", names a MonitorQueryParser type that Lucene does not have either (a Luwak interface); a fix may reword it.

• Who. Readers of the ConcurrentQueryLoader class javadoc who copy its example. No query, document or index file reaches it.
• Default vs opt-in. The loader is an opt-in helper; nothing in Lucene uses it by default. No configuration or special input is involved: the copied example always fails.
• Scale. Every release that has the monitor module, 8.2.0 to 10.6.0 (the six lines are identical in all 49 release tags with the file and in the sources jars of the untagged 8.x releases), and main.
• Effect. A compile error, not wrong behaviour. The example also implies that load errors land in a list the caller passes in; in the real API, IOExceptions thrown by Monitor.register in the loader threads come out of close() as suppressed exceptions of one IOException (on the normal path), so a reader may look for them in the wrong place.
• Priority. Low; the same kind of defect as other stale javadoc examples (for example LFV-1029, LFV-984, LFV-1018 to LFV-1021, LFV-1026).
• Separate bug in the same class. LFV-513 (workers exit at the first exception from Monitor.register; add() can then block forever and close() never reports) is a runtime defect with a different fix site.

The block in the test was checked mechanically against ConcurrentQueryLoader.java:43-48 at 645d4fe14a20 (HTML entities decoded): it is verbatim.

/Example.java:7 in the output is line 7 of the compiled snippet, which is line 43 of ConcurrentQueryLoader.java. javac stops at the missing type; with QueryError replaced by an existing type, the next error is no suitable constructor found for ConcurrentQueryLoader(Monitor,List<Exception>), listing only ConcurrentQueryLoader(Monitor) and ConcurrentQueryLoader(Monitor,int,int) (a separate variant run, not part of this test).

No separate regression test is suggested: this test copies the example, so it would not notice a later edit of the javadoc, and Lucene has no harness that compiles javadoc examples (LUCENE-8488, #9534). Lucene's TestConcurrentQueryLoader.testLoading already runs the corrected form.

# the command above, main 645d4fe14a20, seed DEADBEEF, -ea (-da identical)
There was 1 failure:
1) testClassJavadocExampleCompiles(org.apache.lucene.monitor.TestConcurrentQueryLoaderJavadocExample)
java.lang.AssertionError: [/Example.java:7: error: cannot find symbol
    List<QueryError> errors = new ArrayList<>();
         ^
  symbol:   class QueryError
  location: class Example]
	at __randomizedtesting.SeedInfo.seed([DEADBEEF:9A7EBD6A0F12FB11]:0)
	at org.junit.Assert.fail(Assert.java:89)
	at org.junit.Assert.assertTrue(Assert.java:42)
	at org.apache.lucene.monitor.TestConcurrentQueryLoaderJavadocExample.testClassJavadocExampleCompiles(TestConcurrentQueryLoaderJavadocExample.java:65)
	...
FAILURES!!!
Tests run: 1,  Failures: 1

# the same test on the 10.6.0 release jars, -da: tests_run=1 failures=1, the same single diagnostic

# variant (QueryError replaced by an existing type), not part of the test:
Example.java:8: error: no suitable constructor found for ConcurrentQueryLoader(Monitor,List<Exception>)
    constructor ConcurrentQueryLoader.ConcurrentQueryLoader(Monitor) is not applicable
    constructor ConcurrentQueryLoader.ConcurrentQueryLoader(Monitor,int,int) is not applicable

• Offered as working code. The example is the class's only usage sample, under "Use as follows:" and, since #15573 (2026-01-15), in <code class="language-java">.
• History of the port. In Luwak, ConcurrentQueryLoader(Monitor monitor, List<QueryError> errors) and a QueryError class existed, with this same example. On the never-merged port branch (apache/lucene-solr#648) the "Initial commit" 266d913136e (2019-04-14) imported them, so the example matched. d58aa35f5b8 (2019-04-19, "Refactor the Monitor to take Query objects rather than string representations") deleted QueryError.java, replaced the constructors with (Monitor) and (Monitor, int, int), made close() throw the collected IOExceptions and removed the @param errors lines, but did not touch the example. On #9811 (LUCENE-8766) the author, Alan Woodward, wrote "I've spent a bit of time cleaning up the API and reducing its surface area" (2019-04-16).
• The checked records do not accept the old form. package-info.java, MIGRATE.md and CHANGES.txt (the three places checked) say nothing about the loader's error API or about the example being illustrative.
• Precedent. A stale class-javadoc example was fixed upstream as an ordinary doc fix before: issue #12666 (the Analyzer "Simple example") was closed by PR #12693, merged by msokolov on 2023-10-18. LUCENE-8488 (#9534) asks for compile-checked examples in general.

Strongest case for "intended" or "noise": Lucene does not compile-check javadoc examples (#9534 is open), and in #15225 (2025-10-25) rmuir wrote that "Code examples need to be kept extremely minimal in the rare cases where it does make sense: the maintenance cost is very high and we don't have great validation for these." The block already leaves monitor and getQueries() undeclared, so QueryError could be read as a placeholder; the failure is loud, and the constructor javadoc and the test show the real usage. The cross-model reviews rated this "weak" as an intended-behaviour argument.

Why it fails: a reader supplies context such as monitor, but no context makes a constructor that does not exist compile; even with a QueryError of the reader's own, new ConcurrentQueryLoader(monitor, errors) fails. The block is prescriptive and is the class's only example, and the history shows the example left unchanged during a deliberate API change. rmuir's remark argues for few, minimal examples: it supports fixing or deleting this one, not keeping it broken. Every verifier and the adjudication called it real; the adjudication kept it at Low.

One fix was validated in a scratch worktree of 645d4fe14a20; the alternatives were not run.

Javadoc only, lucene/monitor/src/java/org/apache/lucene/monitor/ConcurrentQueryLoader.java:43-44.

  * <pre><code class="language-java">
- *     List&lt;QueryError&gt; errors = new ArrayList&lt;&gt;();
- *     try (ConcurrentQueryLoader loader = new ConcurrentQueryLoader(monitor, errors)) {
+ *     try (ConcurrentQueryLoader loader = new ConcurrentQueryLoader(monitor)) {
  *         for (MonitorQuery mq : getQueries()) {
  *             loader.add(mq);
  *         }

Trade-offs

None for users: documentation only, and no CHANGES entry is strictly needed. The error behaviour stays undocumented in the class javadoc, as it is today.

What the checks validated

• The block extracted from the patched file (lines 43-44 are the only changed lines), compiled by the same one-test check: passes 1 of 1 on main with assertions on and off and on the 10.6.0 jars. The stock block fails the same test, so the test detects the bug.
• The corrected loop loads queries: a control registered 5 of 5 queries with assertions on and off (it used the (Monitor, 2, 4) constructor; the one-argument form is run by Lucene's own TestConcurrentQueryLoader).
• ./gradlew :lucene:monitor:test --tests "org.apache.lucene.monitor.TestConcurrentQueryLoader" -Ptests.seed=DEADBEEF (the closest suite, which runs the corrected form): 1 test, 0 failures; the whole module, ./gradlew :lucene:monitor:test -Ptests.seed=DEADBEEF: 181 tests, 0 failures, 1 skipped. ./gradlew :lucene:monitor:checkGoogleJavaFormat and :lucene:monitor:renderJavadoc pass, and the rendered class page shows new ConcurrentQueryLoader(monitor) and no QueryError.

For example: "IOExceptions thrown by Monitor#register in the loader threads are rethrown by close() as suppressed exceptions of a single IOException."

Trade-offs

Word it narrowly: only IOExceptions are collected (an unchecked exception from register is not reported), and by LFV-513 add() can block before close() is reached. A broader wording ("If registering queries fails, close() throws ...") would overclaim, as the verifiers noted. If LFV-513's fix changes error reporting, the sentence must follow.

Line 51 names a MonitorQueryParser that Lucene does not have (a Luwak interface).

Trade-offs

Not claimed and not executed; check what thread-safety requirement, if any, still applies before rewording.

In the spirit of rmuir's #15225 remark that code examples are costly to maintain.

Trade-offs

The class loses its only usage sample; the constructor javadoc remains.

The generic wish of LUCENE-8488 (#9534, open since 2018).

Trade-offs

Would stop this class of drift, but it is a build-infrastructure change, not part of this fix.

• First signal. A probe compiled join, memory, monitor, suggest and facet javadoc examples against the stock main 645d4fe14a20 jars and got cannot find symbol: class QueryError on this block (2026-10-29).
• Hunt. A hunt unit for javadoc examples re-ran the lead, extracted the block mechanically, and ran a bytecode scan over 158 builds (1.9.1 to main) for every API member the example uses, with boundaries cross-checked by javac. The scan finds the class from 8.2.0 on, never a QueryError, and only the two real constructors.
• Earlier note. A previous hunt unit (2026-10-26) had mentioned the stale example in passing, without running it, while working on a different bug in the same class (LFV-513).
• Tier. Non-formal: it compiles documentation code and scans jars.