elastic/elasticsearch · error · IllegalArgumentException

found Z value [

Error message

found Z value [

What it means

Thrown by GeographyValidator.checkAltitude when a non-NaN Z (altitude) value is encountered but the validator was configured with ignoreZValue == false (the default strict mode). In strict mode the validator treats altitude as an error because the geographic index path does not store Z; callers must either opt into ignore mode or strip Z before validation.

Source

Thrown at libs/geo/src/main/java/org/elasticsearch/geometry/utils/GeographyValidator.java:90

                "invalid latitude " + latitude + "; must be between " + MIN_LAT_INCL + " and " + MAX_LAT_INCL
            );
        }
    }

    /**
     * validates longitude value is within standard +/-180 coordinate bounds
     */
    protected void checkLongitude(double longitude) {
        if (Double.isNaN(longitude) || longitude < MIN_LON_INCL || longitude > MAX_LON_INCL) {
            throw new IllegalArgumentException(
                "invalid longitude " + longitude + "; must be between " + MIN_LON_INCL + " and " + MAX_LON_INCL
            );
        }
    }

    protected void checkAltitude(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) {
        checkLongitude(x);
        checkLatitude(y);
        checkAltitude(z);
    }

    // validateBBox is intentionally not overridden here: the default implementation (maxY >= minY only,
    // no x-ordinate check) is exactly the geographic policy, since minX may exceed maxX for an
    // antimeridian-crossing envelope.

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

View on GitHub (pinned to db6a809a66)

Solutions

1. If elevation should be silently dropped, use `GeographyValidator.instance(true)` (ignoreZValue=true).
2. If elevation is meaningful, store it in a separate field and strip Z from the geometry before validation.
3. Configure the geo_shape mapper with ignore_z_value=true so the indexing path uses the lenient validator.

Example fix

// before
GeometryValidator v = GeographyValidator.instance(false); // strict
v.validateCoordinate(10.0, 20.0, 50.0); // throws — Z present

// after
GeometryValidator v = GeographyValidator.instance(true); // ignore Z
v.validateCoordinate(10.0, 20.0, 50.0); // ok, Z dropped

boolean hasZ = !Double.isNaN(z);
GeometryValidator v = hasZ ? GeographyValidator.instance(true) : GeographyValidator.instance(false);
v.validateCoordinate(lon, lat, z);

When it happens

Trigger: Calling `validateCoordinate(x, y, z)` or `validate(threeDGeometry)` on a GeographyValidator configured with ignoreZValue=false, where z is a real number (not NaN). The default validator instance (FALSE) is strict.

Common situations: Indexing 3D GeoJSON (with elevation) into a geo_shape field without ignore_z_value=true; mixing 2D and 3D source records where some carry elevation; defaulting to the strict validator and forgetting to set the ignore flag.

Related errors

• only one z value is specified
• invalid latitude
• invalid longitude
• max y cannot be less than min y
• Unknown simplification error calculator:

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