{"record":{"id":"fad470652111e2b7","repo":"elastic/elasticsearch","slug":"found-z-value","errorCode":null,"errorMessage":"found Z value [","messagePattern":"found Z value \\[","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/geo/src/main/java/org/elasticsearch/geometry/utils/GeographyValidator.java","lineNumber":90,"sourceCode":"                \"invalid latitude \" + latitude + \"; must be between \" + MIN_LAT_INCL + \" and \" + MAX_LAT_INCL\n            );\n        }\n    }\n\n    /**\n     * validates longitude value is within standard +/-180 coordinate bounds\n     */\n    protected void checkLongitude(double longitude) {\n        if (Double.isNaN(longitude) || longitude < MIN_LON_INCL || longitude > MAX_LON_INCL) {\n            throw new IllegalArgumentException(\n                \"invalid longitude \" + longitude + \"; must be between \" + MIN_LON_INCL + \" and \" + MAX_LON_INCL\n            );\n        }\n    }\n\n    protected void checkAltitude(double zValue) {\n        if (ignoreZValue == false && Double.isNaN(zValue) == false) {\n            throw new IllegalArgumentException(\"found Z value [\" + zValue + \"] but [ignore_z_value] parameter is [\" + ignoreZValue + \"]\");\n        }\n    }\n\n    @Override\n    public void validateCoordinate(double x, double y, double z) {\n        checkLongitude(x);\n        checkLatitude(y);\n        checkAltitude(z);\n    }\n\n    // validateBBox is intentionally not overridden here: the default implementation (maxY >= minY only,\n    // no x-ordinate check) is exactly the geographic policy, since minX may exceed maxX for an\n    // antimeridian-crossing envelope.\n\n    @Override\n    public void validate(Geometry geometry) {\n        geometry.visit(new GeometryVisitor<Void, RuntimeException>() {\n","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/geo/src/main/java/org/elasticsearch/geometry/utils/GeographyValidator.java#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If elevation should be silently dropped, use `GeographyValidator.instance(true)` (ignoreZValue=true).","If elevation is meaningful, store it in a separate field and strip Z from the geometry before validation.","Configure the geo_shape mapper with ignore_z_value=true so the indexing path uses the lenient validator."],"exampleFix":"// before\nGeometryValidator v = GeographyValidator.instance(false); // strict\nv.validateCoordinate(10.0, 20.0, 50.0); // throws — Z present\n\n// after\nGeometryValidator v = GeographyValidator.instance(true); // ignore Z\nv.validateCoordinate(10.0, 20.0, 50.0); // ok, Z dropped","handlingStrategy":"validation","validationCode":"boolean hasZ = !Double.isNaN(z);\nGeometryValidator v = hasZ ? GeographyValidator.instance(true) : GeographyValidator.instance(false);\nv.validateCoordinate(lon, lat, z);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set ignore_z_value=true on geo_shape fields that should accept 3D input.","Strip Z before validation if elevation is not stored.","Decide on a single Z policy per field and enforce it at the mapper configuration level."],"tags":["geometry","validation","geographic","altitude","z-value","configuration","libs-geo"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}