elastic/elasticsearch · error · IllegalArgumentException

found Z value [

Error message

found Z value [

What it means

StandardValidator.checkZ (line 48) throws IllegalArgumentException when ignoreZValue is false AND the supplied z is not NaN. The validator is the CRS-agnostic default used by both geo_shape and shape parsing (see class Javadoc). It exists to enforce that a field mapping configured with ignore_z_value=false rejects 3D coordinates. The shared TRUE/FALSE singletons (lines 35-36) mean instance(true) silently drops Z, instance(false) strictly rejects it.

Source

Thrown at libs/geo/src/main/java/org/elasticsearch/geometry/utils/StandardValidator.java:50

 */
public class StandardValidator implements GeometryValidator {

    private static final GeometryValidator TRUE = new StandardValidator(true);
    private static final GeometryValidator FALSE = new StandardValidator(false);

    private final boolean ignoreZValue;

    private StandardValidator(boolean ignoreZValue) {
        this.ignoreZValue = ignoreZValue;
    }

    public static GeometryValidator instance(boolean ignoreZValue) {
        return ignoreZValue ? TRUE : FALSE;
    }

    protected void checkZ(double zValue) {
        if (ignoreZValue == false && Double.isNaN(zValue) == false) {
            throw new IllegalArgumentException("found Z value [" + zValue + "] but [ignore_z_value] parameter is [" + ignoreZValue + "]");
        }
    }

    @Override
    public void validateCoordinate(double x, double y, double z) {
        checkZ(z);
    }

    @Override
    public void validate(Geometry geometry) {
        if (ignoreZValue == false) {
            geometry.visit(new GeometryVisitor<Void, RuntimeException>() {

                @Override
                public Void visit(Circle circle) throws RuntimeException {
                    checkZ(circle.getZ());
                    return null;
                }

View on GitHub (pinned to db6a809a66)

Solutions

1. Update the field mapping to set "ignore_z_value": true so 3D ordinates are accepted but ignored — the most common intended behavior.
2. Strip the Z component from incoming coordinates before indexing (project to 2D in your ingestion pipeline / ingest processor).
3. If 3D data is legitimate, remap the field with a method that preserves Z (e.g. geo_shape with ignore_z_value=true) rather than forcing 2D.
4. For programmatic parsing, pass StandardValidator.instance(true) (or GeometryValidator.NOOP) to fromWKT/fromWKB when you do not want Z enforcement.

Example fix

// before — strict 2D, rejects altitude
GeometryValidator v = StandardValidator.instance(false);
v.validateCoordinate(lon, lat, alt); // throws if alt present

// after — accept and ignore altitude
GeometryValidator v = StandardValidator.instance(true);
v.validateCoordinate(lon, lat, alt); // ok, alt dropped

GeometryValidator chooseValidator(boolean ignoreZ, Geometry g) {
    if (ignoreZ) return StandardValidator.instance(true);
    // pre-check: does the geometry carry Z?
    if (geometryHasZ(g)) {
        throw new IllegalArgumentException("mapping rejects Z values; got 3D geometry");
    }
    return StandardValidator.instance(false);
}

// hasZ is exposed on Geometry; for collections, recurse
boolean geometryHasZ(Geometry g) {
    if (g.hasZ()) return true;
    if (g instanceof GeometryCollection<?> c) {
        for (Geometry child : c) if (geometryHasZ(child)) return true;
    }
    return false;
}

try {
    validator.validateCoordinate(x, y, z);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("found Z value")) {
        // strip Z and retry, or surface a mapping-config error to the user
    } else throw e;
}

When it happens

Trigger: Parsing or validating a geometry that carries a non-NaN Z (altitude) value when the field mapping set ignore_z_value=false. Reached via StandardValidator.validateCoordinate(x,y,z) (line 55), via StandardValidator.validate(geometry) which walks every coordinate (lines 60-130), or indirectly through WellKnownText.fromWKT / WellKnownBinary.fromWKB / fromWKT which call validator.validateCoordinate per parsed ordinate. Also triggered by GeometryParser-based REST ingestion when the geo_shape/shape mapping has ignore_z_value disabled.

Common situations: Indexing 3D GeoJSON (coordinates with altitude) into a geo_shape field whose mapping omits or disables ignore_z_value. Switching a field mapping from ignore_z_value=true to false on an index that already contains 3D data (revalidation on reindex). Copying WKT like 'POINT Z(1 2 3)' or 'POINT(1 2 3)' into a 2D-only field. Third-party feeds (aviation, IoT altitude sensors) emitting 3D points into a strict 2D mapping.

Related errors

• Circle is not supported
• holes must have the same number of dimensions as the polygon
• all elements of the collection should have the same number o
• Unknown geometry type: {}
• When specifying 'Z' or 'M', coordinates must include three v

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