A Geo3DPoint polygon query for a degenerate polygon throws NullPointerException instead of matching nothing

Geo3DPoint.newPolygonQuery converts each org.apache.lucene.geo.Polygon with GeoPolygonFactory.makeGeoPolygon, which documents that it returns null "if a valid polygon cannot be generated from this input". That is the case for a ring that encloses no area on the sphere, for example three vertices on the equator: all three lie in the equator's plane, which passes through the planet's centre, and the factory's coplanarity filter finds no valid polygon ("everything was coplanar").

Geo3DUtil.fromPolygon handles that null on purpose: under the comment // Polygon is degenerate it substitutes an empty GeoCompositePolygon, which contains no point. The query then computes the shape's bounding box. An empty composite adds nothing, so all six boxed Double bounds stay null, and the PointInShapeIntersectVisitor constructor unboxes them (PointInShapeIntersectVisitor.java:48 on main 645d4fe14a20). Every search or count that reaches the query's scorer on a segment that has the field throws, with assertions on and off. newShapeQuery with an empty GeoCompositePolygon fails the same way. The same Polygon gives 0 hits with LatLonPoint.newPolygonQuery and is rejected with IllegalArgumentException by newLargePolygonQuery. The failure has been there since 6.1.0 (LUCENE-7192, 2016).

1. Entry. Geo3DPoint.newPolygonQuery calls Geo3DUtil.fromPolygon(planetModel, polygons) and passes the shape to newShapeQuery (Geo3DPoint.java:168-172), which constructs PointInGeo3DShapeQuery (:241-243).
2. The factory says "no polygon". The private Geo3DUtil.fromPolygon(PlanetModel, Polygon) copies the vertices into GeoPoints and calls GeoPolygonFactory.makeGeoPolygon(planetModel, points, holeList) (Geo3DUtil.java:197-227, call at :224). makeGeoPolygon returns null when filterPoints (identical points, too few points) or filterEdges (coplanar points) leaves no valid polygon (GeoPolygonFactory.java:310-320), as its javadoc says (:275-276). For the equator ring filterPoints keeps 3 points and filterEdges returns null ("No path found. This means that everything was coplanar.", :701): the three points all have z = 0: one plane through the planet's centre, a great circle on a sphere (executed).
3. Deliberate substitution. Geo3DUtil.fromPolygon(PlanetModel, Polygon...) maps a null single polygon to new GeoCompositePolygon(planetModel) under // Polygon is degenerate (Geo3DUtil.java:77-84). For a multi-polygon it skips null components (:86-93): a multi-polygon made only of such rings is also an empty composite, while a degenerate ring next to a valid one is just dropped and the query works (executed).
4. The empty shape is right by itself. GeoBaseCompositeShape.isWithin loops over zero shapes and returns false (GeoBaseCompositeShape.java:104-111); getBounds adds nothing (:134-138).
5. Null bounds. The query constructor computes shapeBounds = new XYZBounds(); shape.getBounds(shapeBounds); (PointInGeo3DShapeQuery.java:53-58). XYZBounds keeps its six bounds as boxed Double fields that start null (XYZBounds.java:35-51, "Construct an empty bounds object", :53-54); for the empty composite all six stay null (executed).
6. The unboxing. scorerSupplier returns early only when the segment has no point values for the field (PointInGeo3DShapeQuery.java:78-81); otherwise it builds new PointInShapeIntersectVisitor(result, shape, shapeBounds) (:107). The visitor constructor passes bounds.getMinimumX() and the other five getters to DocValueEncoder.roundDownX(double) and its siblings (PointInShapeIntersectVisitor.java:44-54; PlanetModel.java:771), which unboxes null at :48. Nothing on this path checks for null.
7. Elsewhere null bounds mean "empty". GeoComplexPolygon says "If we have no bounds at all then the answer is \"false\"" (GeoComplexPolygon.java:776-784). The query and the visitor have no such check.

Every ring of the query encloses no area on the sphere: three collinear vertices on the equator or on a meridian; all vertices identical; only two distinct vertices; an A-B-A backtrack; a multi-polygon made only of such rings; and a triangle that is valid and not self-crossing in lat/lon terms but whose vertices lie on one great circle (lat {0, 45.00000000000001, 37.76124390703503, 0}, lon {0, 90, 50.76847951640774, 0}, either winding), which no 2D area check would catch. Also newShapeQuery(field, new GeoCompositePolygon(planetModel)). Not triggered: a degenerate ring next to a valid polygon, a degenerate hole (dropped, count 1), and a segment without the field (count 0).

• Who is hit. Code that indexes Geo3DPoint (@lucene.experimental, Geo3DPoint.java:42) and builds newPolygonQuery from coordinates it does not control, or calls newShapeQuery with a GeoCompositePolygon that can end up empty. Default WGS84 model, codec and IndexWriterConfig; the module is opt-in.
• What goes wrong on search. The request fails with an internal NullPointerException, not a clear argument error, so a server is likely to report it as its own failure. It is thrown before any point is visited: no hang, no extra or missing hits, no index change, and the query cache still answers a normal query afterwards (executed: 20 rounds on a 4-thread searcher with intra-segment partitions). Inside a BooleanQuery the clause makes search throw too.
• Delete path, wider effect (executed on main). IndexWriter#deleteDocuments(query) returns normally because the query is buffered. The next commit() or DirectoryReader.open(writer) throws the same NPE, the writer closes with it as its tragic exception, and the document added after the last commit is lost (2 added, 1 in the last commit). The last commit stays readable and CheckIndex-clean. This is IndexWriter's general rule that an exception while applying a buffered delete is tragic (LUCENE-7868, 2017), not a second bug; with the guard fix the writer stays open.
• Not triggered. A degenerate ring next to a valid polygon, a degenerate hole, or a segment without the field.
• Scale. None: one document, one query, deterministic.
• How likely: rare. Ordinary polygons never trigger it; the recorded searches found no user report in ten years; a read-only GitHub code search (not exhaustive) found no use of Geo3DPoint in Solr, Elasticsearch or OpenSearch.

The test sits in the spatial3d test package like the upstream tests. The one document is needed: in a segment without the field, scorerSupplier returns before it reaches the visitor. It asserts 0 hits, the outcome the guard fix gives, so it is also the regression test for that fix; if maintainers choose to reject the polygon instead, its last two lines become expectThrows(IllegalArgumentException.class, () -> Geo3DPoint.newPolygonQuery(...)).

It needs the org.apache.lucene.tests packages, so it compiles on 9.1.0 and later; releases 6.1.0 to 9.0.0 were checked with a separate history probe on the public API. The test's line numbers in the output include the 16-line license header.

cp $REPRO/TestGeo3DDegeneratePolygonQuery.java $LUCENE/lucene/spatial3d/src/test/org/apache/lucene/spatial3d/
cd $LUCENE && ./gradlew :lucene:spatial3d:test --tests org.apache.lucene.spatial3d.TestGeo3DDegeneratePolygonQuery -Ptests.seed=DEADBEEF

TestGeo3DDegeneratePolygonQuery > testDegeneratePolygonMatchesNothing FAILED
    java.lang.NullPointerException: Cannot invoke "java.lang.Double.doubleValue()" because the return value of "org.apache.lucene.spatial3d.geom.XYZBounds.getMinimumX()" is null
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:399007E39E65274F]:0)
        at org.apache.lucene.spatial3d.PointInShapeIntersectVisitor.<init>(PointInShapeIntersectVisitor.java:48)
        at org.apache.lucene.spatial3d.PointInGeo3DShapeQuery$1.scorerSupplier(PointInGeo3DShapeQuery.java:107)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.LRUQueryCache$CachingWrapperWeight.scorerSupplier(LRUQueryCache.java:874)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.IndexSearcher.searchLeaf(IndexSearcher.java:842)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:814)
        ...
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.IndexSearcher.count(IndexSearcher.java:528)
        at org.apache.lucene.spatial3d.TestGeo3DDegeneratePolygonQuery.testDegeneratePolygonMatchesNothing(TestGeo3DDegeneratePolygonQuery.java:42)

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

# standalone runner, seed DEADBEEF: main -ea and -da, 10.6.0, 10.5.2: 1 of 1 fails at PointInShapeIntersectVisitor.java:48; 9.12.3: at :47

• Deliberate branch. Geo3DUtil.fromPolygon builds an empty GeoCompositePolygon under // Polygon is degenerate (Geo3DUtil.java:79-81) and skips degenerate components of a multi-polygon (:89-91). An empty composite contains no point (GeoBaseCompositeShape.java:104-111). That is consistent with "match nothing".
• The factory's null is documented (GeoPolygonFactory.java:275-276), and Karl Wright confirmed on #9568 (2018-10-05) that "It's actually in the GeoPolygonFactory contract that null is returned for polygons that cannot be constructed". Five minutes earlier on the same issue he had written "I agree that the factory should never return null; it should return IllegalArgumentException instead. This would have to be a fix in the factory.", which supports the reject fix as much as it explains the null.
• The query assumes non-null bounds. When the predecessor query (bkdtree3d PointInGeo3DShapeQuery$1.scorer, on the LUCENE-6699 branch) hit an NPE from null bounds in 2015 (#7757), Karl Wright answered "They are not expected to be null" and fixed the shapes. The empty-composite branch came later (LUCENE-7192, 2016) and breaks that assumption.
• Contract. newPolygonQuery's javadoc says the polygon "should have a limited number of edges (less than 100) and be well-defined, with well-separated vertices" (Geo3DPoint.java:157-159): advice, with no @throws. newShapeQuery states no precondition (:235-243). Polygon checks only length, closure and coordinate ranges (Polygon.java:77-101).
• Siblings. LatLonPoint.newPolygonQuery returns 0 hits for the same Polygon; newLargePolygonQuery rejects it when the query is built (IllegalArgumentException: cannot find a point that is inside the polygon); the spatial-extras wrapper throws InvalidShapeException("Invalid polygon, all points are coplanar") for the same factory null (Geo3dShapeFactory.java:350-353, the #9568 fix). None ends in an NPE at search time.
• Tests. No upstream test builds a query from a degenerate polygon or an empty composite: TestGeo3DPoint's random polygon queries catch IllegalArgumentException and draw again (TestGeo3DPoint.java:771-793). With either fix all existing spatial3d tests pass (executed).
• History. Before LUCENE-7192 the three inputs run at that commit (the equator ring, the all-identical ring and the two-distinct-vertex ring) were rejected with IllegalArgumentException when the query was built (executed on the spatial3d sources of branch_6x b95bbb80927; the A-B-A ring and the great-circle triangle were not run there). LUCENE-7192 ("Geo3d polygon creation should not get upset about co-linear points", for OpenStreetMap data) made the factory return null and added the empty-composite branch to be more tolerant; neither it nor LUCENE-7221 mentions a query-time failure.

The strongest "works as designed / misuse" case (the devil's-advocate verifier and the cross-model reviewers): the javadoc says the polygon "should be well-defined"; Polygon says it "must not be self-crossing, otherwise may result in unexpected behavior" (Polygon.java:34), and a collinear or A-B-A ring retraces itself; maintainers prefer rejecting degenerate polygons (#9568, newLargePolygonQuery, the Tessellator's "at least three non-collinear points required", TestTessellator.java:200-207); and Geo3DPoint is @lucene.experimental.

Why it fails: all of that supports at most a clear IllegalArgumentException when the query is built, not an NPE at search time; the great-circle triangle does not self-cross in lat/lon terms and still throws; @lucene.experimental is about API stability, not a licence to crash; the code explicitly accepts and converts this input; and newShapeQuery with an empty composite involves no polygon at all. Verdict: not intended, a defect.

Both options were validated with gradle in a fresh worktree at 645d4fe14a20 (seed DEADBEEF). They differ in what a degenerate polygon means: no hits, or an error when the query is built. Both remove the NullPointerException for newPolygonQuery; only the guard also covers newShapeQuery with an empty composite, so the two can be combined.

In PointInGeo3DShapeQuery's scorerSupplier, right after the existing values == null check (PointInGeo3DShapeQuery.java:79-81). Returning null is the usual "no matches in this segment" answer, so the query cache and the delete path need nothing else.

        if (shapeBounds.getMinimumX() == null) {
          // The shape added nothing to its bounds (e.g. the empty GeoCompositePolygon that
          // Geo3DUtil builds for a degenerate polygon): it contains no point.
          return null;
        }

Trade-offs

• Silent: a client that sends a broken polygon gets no hits and no error, as with LatLonPoint.
• The guard checks getMinimumX() only, as the original sketch does. That is enough for the empty composite (all six stay null), but XYZBounds sets each axis separately (addXValue, addYValue, addZValue, XYZBounds.java:317, :340, :363), so checking all six bounds is equally cheap and more defensive.

What the checks validated

• Gradle, fresh worktree at 645d4fe14a20, seed DEADBEEF: the minimal test fails before the change (1 test, 1 failure) and passes after it, with assertions on and with -Ptests.asserts=false; ./gradlew :lucene:spatial3d:test passes (182 tests: the module's 181 plus the new one, 3 skipped).
• With the same guard on the stock jars: an independent six-test suite (two controls, equator and meridian rings, an all-degenerate multi-polygon, newShapeQuery with an empty composite) passes 6 of 6, upstream TestGeo3DPoint passes (15 passed, the 2 @Nightly tests skipped; assertions on), and the delete-path probe keeps the writer open and commits both documents.

In the package-private varargs Geo3DUtil.fromPolygon(PlanetModel, Polygon...) (Geo3DUtil.java:71, called by Geo3DPoint.newPolygonQuery), throw instead of building an empty composite: for a single degenerate polygon, and for a multi-polygon whose components are all degenerate.

      if (component == null) {
        throw new IllegalArgumentException("polygon is degenerate: it encloses no area");
      }
      ...
      if (poly.size() == 0) {
        throw new IllegalArgumentException("all polygons are degenerate: they enclose no area");
      }

Trade-offs

• Consistent with the #9568 fix in spatial-extras, newLargePolygonQuery and the Tessellator, and with Karl Wright's 2018 "the factory should never return null; it should return IllegalArgumentException instead" (#9568); it tells the caller what is wrong.
• Does not cover newShapeQuery(field, new GeoCompositePolygon(pm)), which never passes through fromPolygon; the guard is still needed for that path.
• Turns a call that works today into an error: on an index whose segments have no Geo3DPoint values the query currently returns 0 hits (executed).
• Keeps the mixed case working (a degenerate ring next to a valid one is still dropped); a stricter variant that rejects every degenerate component would also break that case and degenerate holes (not run).
• Also changes the other caller of fromPolygon, Geo3DDocValuesField.newOutsidePolygonSort (Geo3DDocValuesField.java:311-313): a degenerate polygon would throw there too when the sort is built (not run).

What the checks validated

• Gradle, same worktree: newPolygonQuery throws IllegalArgumentException: polygon is degenerate: it encloses no area for the repro's input (so the minimal test, which asserts 0 hits, fails by design); ./gradlew :lucene:spatial3d:test without the minimal test passes (181 tests, 3 skipped).

• Method: code reading (not a formal method). While building a metamorphic test harness for the spatial3d geometry code, an AI tool noticed the explicit // Polygon is degenerate branch in Geo3DUtil.fromPolygon and, separately, the unconditional unboxing of XYZBounds in the PointInShapeIntersectVisitor constructor, and asked what an empty shape's bounds are.
• It ran a set of degenerate but legal polygons on the stock main jar, then wrote a public-API JUnit test, which failed on main with assertions on and off (20 of 20 iterations) and on 10.5.2 and 9.12.3, and passed with the null-bounds guard.
• Independent checkers then reproduced it with their own tests, widened the trigger set (the great-circle triangle, newShapeQuery with an empty composite) and found the delete-path effect.