elastic/elasticsearch · error · IllegalArgumentException

Linear ring is not supported by WKB

Error message

Linear ring is not supported by WKB

What it means

WellKnownBinary.toWKB's public visitor has a visit(LinearRing) override (line 179) that unconditionally throws IllegalArgumentException. LinearRing is intentionally not a standalone WKB type — it only exists as the structural innards of a Polygon. The private visitLinearRing (line 183) is used internally by the Polygon visitor to write ring data; a bare LinearRing reaching the top-level visitor is a caller bug.

Source

Thrown at libs/geo/src/main/java/org/elasticsearch/geometry/utils/WellKnownBinary.java:180

                if (rectangle.isEmpty()) {
                    throw new IllegalArgumentException("Empty " + rectangle.type() + " cannot be represented in WKB");
                }
                writeInt(out, scratch, rectangle.hasZ() ? 1018 : 18);
                // minX, maxX, maxY, minY
                writeDouble(out, scratch, rectangle.getMinX());
                writeDouble(out, scratch, rectangle.getMaxX());
                writeDouble(out, scratch, rectangle.getMaxY());
                writeDouble(out, scratch, rectangle.getMinY());
                if (rectangle.hasZ()) {
                    writeDouble(out, scratch, rectangle.getMinZ());
                    writeDouble(out, scratch, rectangle.getMaxZ());
                }
                return null;
            }

            @Override
            public Void visit(LinearRing ring) {
                throw new IllegalArgumentException("Linear ring is not supported by WKB");
            }

            private void visitLinearRing(LinearRing ring) {
                writeInt(out, scratch, ring.length());
                for (int i = 0; i < ring.length(); i++) {
                    writeDouble(out, scratch, ring.getX(i));
                    writeDouble(out, scratch, ring.getY(i));
                    if (ring.hasZ()) {
                        writeDouble(out, scratch, ring.getZ(i));
                    }
                }
            }
        });
    }

    private static void writeInt(ByteArrayOutputStream out, ByteBuffer scratch, int i) {
        scratch.clear();
        scratch.putInt(i);

View on GitHub (pinned to db6a809a66)

Solutions

1. Wrap the LinearRing in a Polygon before serializing: new Polygon(linearRing) or new Polygon(shell, holes).
2. Ensure you pass the Polygon (which contains the ring) to toWKB, never a bare LinearRing.
3. Add an instanceof guard before toWKB to reject LinearRing inputs at the API boundary.

Example fix

// before
LinearRing shell = new LinearRing(lons, lats);
byte[] wkb = WellKnownBinary.toWKB(shell, ByteOrder.LITTLE_ENDIAN); // throws

// after
Polygon polygon = new Polygon(shell);
byte[] wkb = WellKnownBinary.toWKB(polygon, ByteOrder.LITTLE_ENDIAN);

Geometry ensureNotBareRing(Geometry g) {
    if (g instanceof LinearRing r) return new Polygon(r);
    return g;
}

static boolean isBareLinearRing(Geometry g) { return g instanceof LinearRing; }

try {
    return WellKnownBinary.toWKB(g, bo);
} catch (IllegalArgumentException e) {
    if (g instanceof LinearRing r) return WellKnownBinary.toWKB(new Polygon(r), bo);
    throw e;
}

When it happens

Trigger: Calling WellKnownBinary.toWKB(linearRing, byteOrder) where the argument is a standalone LinearRing (not wrapped in a Polygon). Constructing a Polygon manually but accidentally passing its shell ring (polygon.getPolygon()) instead of the polygon itself to toWKB.

Common situations: Custom geometry builders that assemble LinearRing shells/holes and then serialize the ring rather than the containing Polygon. Refactoring that extracts ring handling and accidentally routes a ring into the top-level serializer. Misuse of the public toWKB API with internally-typed objects.

Related errors

• Linear ring is not supported by WKT
• Empty
• holes must have the same number of dimensions as the polygon
• Unknown geometry type:
• Empty POINT cannot be represented in WKB

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/743d97bdd8cccf71. Report an issue: GitHub.