JapaneseCompletionFilterFactory upper-cases the default mode instead of the configured value, so mode="query" is rejected

JapaneseCompletionFilterFactory (SPI name japaneseCompletion) reads its mode argument with Mode.valueOf(get(args, MODE_PARAM, DEFAULT_MODE.name().toUpperCase(Locale.ROOT))). The toUpperCase is applied to the default, the constant name "INDEX", so it does nothing, and the configured value reaches the case-sensitive Enum.valueOf unchanged: mode="query" throws IllegalArgumentException: No enum constant org.apache.lucene.analysis.ja.JapaneseCompletionFilter.Mode.query from the constructor and through CustomAnalyzer, and only INDEX and QUERY work. The sibling JapaneseTokenizerFactory in the same module uses the same idiom with the parenthesis after get(...) and accepts lower-case modes. The expression has been there since the factory was added (LUCENE-10102, #297, 2021) and is in every release from 9.0.0 to 10.6.0 and on main. No javadoc promises case-insensitive values, so this is a minor consistency defect, not a broken contract: it fails loudly when the analyzer is built, never picks the wrong mode and never affects tokens or an index. Moving .toUpperCase(Locale.ROOT) onto the result of get(...) fixes it.

• JapaneseCompletionFilter.Mode: an enum with the constants INDEX and QUERY (JapaneseCompletionFilter.java:74-79 at 645d4fe14a20); DEFAULT_MODE = Mode.INDEX (:61).
• AbstractAnalysisFactory.get(args, name, defaultVal): removes the argument from the map and returns it as given, or the default when it is absent (AbstractAnalysisFactory.java:160-163).
• Enum.valueOf: case-sensitive; any string that is not exactly a constant name throws IllegalArgumentException: No enum constant ....

1. The constructor parses the mode (JapaneseCompletionFilterFactory.java:46-51):

mode =
    JapaneseCompletionFilter.Mode.valueOf(
        get(
            args,
            MODE_PARAM,
            JapaneseCompletionFilter.DEFAULT_MODE.name().toUpperCase(Locale.ROOT)));

1. The closing parenthesis of get(...) comes after the toUpperCase, so the call belongs to the third argument, the default. DEFAULT_MODE.name() is already "INDEX"; upper-casing it can never change anything.
2. The configured value, for example "query", is returned unchanged and Mode.valueOf("query") throws.
3. The sibling JapaneseTokenizerFactory puts the call on the configured value: Mode.valueOf(get(args, MODE, JapaneseTokenizer.DEFAULT_MODE.toString()).toUpperCase(Locale.ROOT)) (JapaneseTokenizerFactory.java:122-124); KoreanTokenizerFactory does the same (KoreanTokenizerFactory.java:92-95).

• A probe of 19 mode values, each through the constructor and through CustomAnalyzer: only exactly INDEX and QUERY were accepted, each giving its own mode; query, Query, index, ' QUERY' and the others were rejected. On the input 東京ｔ, INDEX gives [東京, toukyou, t, thiー, texiー] and QUERY gives [東京t, toukyout].
• With the fix the lower- and mixed-case spellings probed (7 ASCII variants such as query, Query, qUERY and iNDEX, plus ındex) give the mode they name, and the other values are still rejected.

• Who is hit. Only users of the factory. JapaneseCompletionAnalyzer builds the filter directly, not through the factory, so it is not affected; neither is code that constructs JapaneseCompletionFilter or JapaneseCompletionAnalyzer directly, since their constructors take the Mode enum or pick INDEX when none is given, and never parse a string.
• What it takes. Writing the query-side mode in lower or mixed case. That is the natural spelling next to the sibling tokenizer: its factory accepts lower case, its upstream test passes "normal", and the Solr reference guide documents lower-case modes for it.
• What happens. A deterministic IllegalArgumentException when the factory is constructed, naming the enum. It never selects the other mode, never yields wrong tokens and never reaches an index.
• Scale. Minor: a loud configuration-time nit with a one-word workaround, unreported since 9.0.0 (2021).

The map is a mutable HashMap because the factory removes the arguments it consumes. The same exception comes out of CustomAnalyzer.builder().withTokenizer("japanese", "mode", "normal").addTokenFilter("japaneseCompletion", "mode", "query").build(), which calls the same constructor through AnalysisSPILoader.newFactoryClassInstance. The test compiles on 9.1.0 and later (where LuceneTestCase lives in org.apache.lucene.tests.util); 9.0.0 was checked with a main() form making the same calls.

As the regression test: the same test, for example as a new method in TestJapaneseCompletionFilterFactory.

cp TestJapaneseCompletionFilterFactoryLowerCaseMode.java $LUCENE/lucene/analysis/kuromoji/src/test/org/apache/lucene/analysis/ja/
cd $LUCENE && ./gradlew :lucene:analysis:kuromoji:test --tests org.apache.lucene.analysis.ja.TestJapaneseCompletionFilterFactoryLowerCaseMode -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

# gradle, main 645d4fe14a20, seed DEADBEEF (the same with -Ptests.asserts=false)
TestJapaneseCompletionFilterFactoryLowerCaseMode > testLowerCaseMode FAILED
    java.lang.AssertionError: expected mode=query to be upper-cased to QUERY, but the factory threw: java.lang.IllegalArgumentException: No enum constant org.apache.lucene.analysis.ja.JapaneseCompletionFilter.Mode.query
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:8EC20BA6F19FBC63]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at org.apache.lucene.analysis.ja.TestJapaneseCompletionFilterFactoryLowerCaseMode.testLowerCaseMode(TestJapaneseCompletionFilterFactoryLowerCaseMode.java:29)

# where it is thrown (the hunt's earlier tests, which let the exception escape; same lines at 645d4fe14a20)
java.lang.IllegalArgumentException: No enum constant org.apache.lucene.analysis.ja.JapaneseCompletionFilter.Mode.query
  at org.apache.lucene.analysis.ja.JapaneseCompletionFilterFactory.<init>(JapaneseCompletionFilterFactory.java:47)
  (through CustomAnalyzer the same exception, with AnalysisSPILoader.newFactoryClassInstance(AnalysisSPILoader.java:195) in its stack)

• The dead call. DEFAULT_MODE.name().toUpperCase(Locale.ROOT) is always "INDEX" (JapaneseCompletionFilterFactory.java:51, JapaneseCompletionFilter.java:61).
• Sibling convention, same module. JapaneseTokenizerFactory has upper-cased the configured value since at least 2013 (LUCENE-4877, 6de43dea0af, which introduced the get(...).toUpperCase(Locale.ROOT) form); KoreanTokenizerFactory (:92-95) and Word2VecSynonymFilterFactory (:58) do the same.
• Tests. TestJapaneseTokenizerFactory.testMode passes "normal"; the completion factory's only mode test passes "QUERY" (TestJapaneseCompletionFilterFactory.java:36), and no test asserts that lower case is rejected.
• History. The factory came in one commit, 4e86df96c03 (LUCENE-10102, #297, by Tomoko Uchida, co-authored by Robert Muir, 2021-09-17), with this exact expression, and the file has never been edited since. None of the PR's review comments or the issue's comments is about the mode argument or its case.
• Project convention. In LUCENE-4877 (#5942, 2013) Steven Rowe proposed a getEnum(...) helper for factory arguments, "probably case insensitivity could be assumed?", and Robert Muir replied "+1 to all of this". Context only, eight years before this factory.

The strongest case for "intended" (an intended-behaviour checker, and a read-only reviewer from another model family, OpenAI GPT-5.6, which leaned "not real"): the only documentation is "mode: Completion mode. see JapaneseCompletionFilter.Mode" (JapaneseCompletionFilterFactory.java:30), whose constants are INDEX and QUERY; the upstream test uses QUERY; even JapaneseTokenizerFactory's javadoc example writes mode="NORMAL" (:43); BeiderMorseFilterFactory is case-sensitive (a plain valueOf at :58-59, and its javadoc example uses upper-case values); and the failure is loud, immediate and has a one-word workaround.

Why it fails: it shows there is no broken contract, which is why this is classed as a minor consistency defect, but not that case sensitivity was chosen. BeiderMorseFilterFactory has no toUpperCase call at all, so it is no precedent for a misplaced one; this factory's mode expression does call toUpperCase(Locale.ROOT), and only the call's placement (on the default instead of the configured value) makes it useless. No javadoc, test, CHANGES.txt, MIGRATE.md, review or issue comment says the case sensitivity is deliberate. This is still an inference about intent: a maintainer could reasonably prefer option B or decline.

One option was run through gradle in a scratch worktree of 645d4fe14a20 and is recommended; the alternatives were not run.

In the constructor (JapaneseCompletionFilterFactory.java:46-51), move .toUpperCase(Locale.ROOT) onto the result of get(...).

     mode =
         JapaneseCompletionFilter.Mode.valueOf(
-            get(
-                args,
-                MODE_PARAM,
-                JapaneseCompletionFilter.DEFAULT_MODE.name().toUpperCase(Locale.ROOT)));
+            get(args, MODE_PARAM, JapaneseCompletionFilter.DEFAULT_MODE.name())
+                .toUpperCase(Locale.ROOT));

Trade-offs

• Lower- and mixed-case spellings of INDEX and QUERY are accepted and give the mode they name (7 ASCII variants probed, such as query, Query, qUERY, iNDEX); any other value is still rejected with the same exception type (its message then shows the upper-cased value). Upper-case configurations behave as before; no signature or index-format change, but construction-time parsing becomes more permissive (values rejected today are accepted).
• As in JapaneseTokenizerFactory, Locale.ROOT upper-casing maps U+0131 (dotless i) to I, so ındex is accepted as INDEX; harmless for a trusted configuration value and independent of the JVM default locale.

What the checks validated

• Gradle in a scratch worktree of 645d4fe14a20 (2026-11-01): stock, the minimal test fails with assertions on and off; with the fix it passes both ways.
• With the fix: TestJapaneseCompletion* (analyzer, filter, factory and the repro) 4 classes, 12 tests, 0 failures; the whole kuromoji module 31 classes, 196 tests, 0 failures (7 skipped by the test framework); :lucene:analysis:kuromoji:check -x test passes (formatting, ecjLint, forbiddenApis).
• Earlier: the same change shadowed into the stock jars passes the hunt's 3-test and 4-test JUnits (which also check the QUERY-mode tokens) and the main() form on 9.0.0.

For example "mode: INDEX (default) or QUERY, case-insensitive" next to the existing "see JapaneseCompletionFilter.Mode" line.

Trade-offs

Documentation only; makes the accepted spellings explicit. Not run.

Replace the default with JapaneseCompletionFilter.DEFAULT_MODE.name() and state in the javadoc that only INDEX and QUERY are accepted.

Trade-offs

No behaviour change, so no configuration changes meaning; but the completion filter factory stays deliberately stricter than the tokenizer factory it is configured next to, and the lower-case spelling stays a trap. Not run.

Method: non-formal (code reading, then executed tests). The hunt unit was checking that the #16416 rewrite of JapaneseCompletionFilter's output buffering keeps its behaviour. Reading the factory that constructs the filter under test, the finder saw DEFAULT_MODE.name().toUpperCase(Locale.ROOT), a call that cannot change the already upper-case constant name "INDEX". A 3-test public-API JUnit (control: JapaneseTokenizerFactory with mode=search; claims: the factory and CustomAnalyzer with mode=query) reproduced it on main, 10.5.2 and 9.1.0. Independent checkers then reproduced it with their own tests, and it was cut to the one-test repro.