SimpleQueryParser skips the operator typed directly after a phrase slop, so "a b"~2+c means phrase OR c

SimpleQueryParser's javadoc says that whitespace and ( ) + | " delimit tokens, that a phrase is a token, that token1+token2 is AND and token1|token2 is OR (written without spaces), and that "term1 term2"~5 is a near query. When a phrase with a slop is followed directly by one of those delimiters, the parser skips the delimiter: "a b"~2+c becomes f:"a b"~2 f:c (OR) instead of +f:"a b"~2 +f:c, although "a b"~2 +c and "a b"+c both give the AND. On the documents "new york pizza", "new york bagels" and "chicago pizza", "new york"~2+pizza matches 3 documents instead of 1.

The cause is an off-by-one in consumePhrase: parseFuzziness reads the slop digits and stops on the delimiter after them, and the unconditional ++state.index that follows, written in 2013 to step over the closing quote, then steps over that delimiter. It needs the default flags only, raises no error, and is in every release since 4.7.0 (2014), the first with the ~ operator. The fix is one condition: skip the closing quote only when there was no slop.

• Slop (near query). "a b"~2 is a phrase whose words may be up to 2 positions apart (PhraseQuery(2, "f", "a", "b")). An empty ~ followed by another character means slop 2 (since 6.5.0); a ~ at the very end of the input means no slop.
• Default operator. What two tokens with nothing between them combine with: OR, unless setDefaultOperator(MUST).
• Delimiter. A character that ends a token: whitespace, ", |, +, ( or ) (javadoc SimpleQueryParser.java:41-42, tokenFinished :536-550).

The expected column is what the javadoc's operators define and what the same input with a space after the slop gives on main; the slop 2 of an empty ~ is the parser's own rule, not a javadoc statement. Not affected: "a b"+c (no slop), the fuzzy term a~1+b, a ) that closes a group right after the slop ((x|"a b"~2)+c), and an extraneous ) ("a b"~2)c), which is ignored either way.

Further cases (executed on main, 10.5.2 and with the fix):

• A glued + under default AND, or | under default OR, is skipped too. When a token follows, the default operator then gives the same query; when a second operator follows, it does not, because the parser keeps the first explicit operator: under default AND "a b"~2+|c gives OR on main and AND with a space or the fix.
• The skip also follows slop text that does not parse: "a b"~x+c gives slop 0 and loses the + (f:"a b" f:c), and so do "a b"~1a+c and "a b"~2\+c.
• An empty phrase: a""~+a gives f:a f:a instead of +f:a +f:a.

1. consumePhrase (SimpleQueryParser.java:296-364) reads the phrase up to its closing quote. If ~ and more characters follow, it moves onto the ~ and sets hasSlop (:317-324).
2. parseFuzziness (:495-533, called at :356) advances from the ~ and stops at the first delimiter (:505-507), so the index is left on the +.
3. consumePhrase then always runs ++state.index (:362). That line dates from 2013, when the index was always on the closing quote there. After a slop it skips the +, and the parse loop never sees it.
4. The lost + or | leaves the next token to the default operator; a lost quote turns the next phrase into separate terms; a lost ( merges the group into the main sequence.
5. consumeToken calls the same parseFuzziness for fuzzy terms (:410) with no trailing increment, so a~1+b keeps its AND. A group's ) is safe because consumeSubQuery parses the group's inner text as its own substring (:288-289).

// SimpleQueryParser.java:355-362
if (hasSlop) {
  branch = newPhraseQuery(phrase, parseFuzziness(state)); // returns with the index ON the delimiter
} else {
  branch = newPhraseQuery(phrase, 0);
}
buildQueryTree(state, branch);

++state.index; // meant to step over the closing quote; after a slop it skips the delimiter

• Who is exposed. Every caller of SimpleQueryParser with the default flags: the two-argument and the weights constructors pass -1 (SimpleQueryParser.java:141-148), which includes NEAR_OPERATOR. Nothing has to be configured. There is no other in-tree caller outside the parser's own package.
• What it takes. A +, |, " or ( typed directly after the slop digits, after an empty ~, or after slop text that does not parse (~x). Glued operators are the documented style of this syntax (token1+token2), so users who write "new york"~2+pizza, and code that builds query strings by concatenation, can produce it.
• What goes wrong. A query of the wrong structure, silently. Under default OR it over-matches: AND becomes OR, AND NOT becomes OR NOT, a phrase becomes loose terms. Under default AND a glued | under-matches: OR becomes AND, while a lost quote still widens the query (the second phrase becomes required loose terms: 2 hits instead of 1 on the documents "a b c d" and "a b d c"). A lost ( can go either way. No exception, crash or index change.
• Downstream (by code reading only, not run). Elasticsearch's and OpenSearch's simple_query_string parsers and Solr's simple query parser extend SimpleQueryParser; consumePhrase is private, so they inherit the parse loop.
• How likely. Rare: slop is an advanced feature, the upstream test writes "foo bar"~12 baz with a space, the most natural glued case (a ) closing a group) is unaffected, and the searches found no prior report (see Prior reports).
• Opt-out. The targeted opt-out is turning NEAR_OPERATOR off, which disables phrase slop altogether; turning off the phrase operator or the operator that follows also removes the path, but disables more syntax. The practical workaround is a space after the slop digits.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<+field:"a b"~2 +field:c> but was:<field:"a b"~2 field:c>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.queryparser.simple.TestSimpleQueryParserSlopOperator.testAndDirectlyAfterPhraseSlop(TestSimpleQueryParserSlopOperator.java:27)

• Contract. SimpleQueryParser.java:40-42: "Tokens are considered to be any of a term, phrase, or subquery ... Whitespace ... and certain operators may be used to delimit tokens ( ) + | \" ." :50-51: "'+' specifies AND operation: token1+token2", "'|' specifies OR operation: token1|token2". :56: "'~N' at the end of phrases specifies near query: \"term1 term2\"~5".
• Upstream tests. testORPhrase requires "foo bar"|"star wars" to be an OR although the test helper's default operator is AND, so an operator glued to a phrase must be honoured (testANDPhrase agrees, but under that default it cannot tell a kept + from a dropped one). No test covers an operator glued to a slop; testPhraseWithSlop checks "foo bar"~12 baz with a space, which the skip does not harm, so it is not evidence either way. With the fix all 46 TestSimpleQueryParser tests pass.
• The parser's own consistency. parseFuzziness ends the slop exactly at the + because tokenFinished says it is a delimiter, and then the delimiter is discarded. The fuzzy-term path calls the same helper without the extra step and keeps the operator.
• History. The ++state.index came with the class (LUCENE-5336, 2013), when the index was always on the closing quote at that point. LUCENE-5410 (2014) put the slop branch in front of it without changing it. Its review noted that the term and phrase paths differ "in how they consume/increment state.data and state.index", but no comment discusses an operator after a slop. No CHANGES, MIGRATE or javadoc text describes the skip.

The strongest "works as designed" case (the GPT-5.6 reviews, the devil's advocate and the adjudication looked for it): the javadoc promises only a best effort, "Any errors in query syntax will be ignored and the parser will attempt to decipher what it can; however, this may mean odd or unexpected results", and slop parsing is lenient on purpose ("foo bar"~1a and "foo bar"~-1 silently give slop 0 in an upstream test). A maintainer could call an operator glued to a slop badly composed input. They could also point out that no upstream example or test puts an operator right after a slop, that - is not a delimiter and is swallowed into the slop text, and that the behaviour has not changed in twelve years, so a stored query could depend on it.

Why it fails: the input is not a syntax error, since the javadoc defines every piece of it; the parser itself recognizes the + as the end of the slop and then throws it away; the same delimiter is honoured after a space, after a phrase without slop and after a fuzzy term; the lenient tests are about the slop text itself, while the + after a valid ~2 is outside it; and the cause is a leftover increment from before the slop feature, not a decision. Twelve years of the same behaviour argue for a CHANGES entry, not for keeping a skip that no documentation describes. Verdict: not intended, a defect.

One fix was built and validated in a scratch worktree at ea57360912ed (option A), together with a variant that moves the same line (option B).

fix.diff, +5/-1 in SimpleQueryParser.java. Without a slop the index is on the closing quote (or a trailing ~ at the end of the input) and must be skipped as before. With a slop, parseFuzziness has already consumed the ~ and the digits and stands on the delimiter or at the end of the input, so nothing is left to skip; the parse loop then handles the delimiter as it does after a space.

      buildQueryTree(state, branch);

-      ++state.index;
+      if (hasSlop == false) {
+        // skip the closing quote (or a trailing '~'); after a slop, parseFuzziness already left the
+        // index on the delimiter that ended it, which must still be parsed, or at the end of input
+        ++state.index;
+      }
    }
  }

Trade-offs

• The resulting query changes only when a +, |, " or ( follows the slop text: after a valid or empty slop (the bug), and also after slop text that does not parse ("a b"~x+c), which then parses like its spaced form. Whitespace, an extraneous ) and the end of input give the same query as before (executed).
• A stored query written in the glued shape and tuned to today's result would now parse as documented, so a CHANGES entry under bug fixes is worth adding.
• Not reviewed by a committer.

What the checks validated

• Stock: this doc's test fails 6 of 7 with assertions on and off; with the fix all 7 pass.
• The simple package (TestSimpleQueryParser 46 tests and the new test), assertions on and off: 53 tests, 0 failures.
• The whole queryparser module: 31 classes, 540 tests, 0 failures, 1 skipped.
• :lucene:queryparser:check -x test passes (google-java-format, ecjLint, forbiddenApis).
• Every earlier hunt test with the fix shadowed on the main jars passes (the finder's 4, the independent reproducer's 6 and its empty-slop test, the cross-model review stage's 5, the devil's advocate's 3), and the security probe gives the spaced results.
• The finder's two exhaustive harnesses with the same one-condition change report 0 mismatches (10,047,388 and 2 x 11,413,636 checks).
• After the fact checks the patch's code comment was reworded (comment only): both diffs apply to ea57360912ed, google-java-format finds nothing to change, and this doc's test passes 7 of 7 with it, assertions on and off.

option-b-move-increment.diff: put ++state.index in the else branch next to newPhraseQuery(phrase, 0). It reads as "skip the closing quote where it is still the current character".

Trade-offs

Same behaviour as the recommended option; a matter of style.

What the checks validated

The simple package passes: 53 tests, 0 failures (assertions on).

Change the shared helper instead of the phrase path.

Trade-offs

Not recommended and not tested: the fuzzy-term caller relies on the index being left on the delimiter, so it would break a~1+b.

Put a space after the slop digits ("a b"~2 +c); applications that build query strings should do the same, and keep access restrictions in a separate FILTER clause.

Trade-offs

Avoids the symptom; does not fix the parser.

Method: bounded-exhaustive checking on the stock jar (the hunt's semi-formal tier; no model checker, SMT solver or prover).

• In a hunt unit (query parsers, 2026-10-26) the finder, an AI tool, saw the off-by-one by reading consumePhrase while building two harnesses. Its first run, every string of up to 5 characters, found nothing: the bug needs at least 6.
• Metamorphic check. "A space next to an operator does not change the query", over every string of up to 7 characters over a + | - " ~ 1 and space: 2,396,745 strings, 10,047,388 checks, 819 mismatches per default operator, every one a phrase followed by ~.
• Translation validation. An independent reference semantics of the documented grammar, evaluated as match sets on all 40 documents of up to 3 tokens over {a, b, c}: 11,413,636 checks per default operator, 354,538 (OR) and 349,990 (AND) mismatches, every one an operator directly after phrase~N.
• With the fix both harnesses report 0 mismatches. The finder then wrote a deterministic public-API JUnit; the independent checks, history sweep, prior-report search and security assessment followed.