{"record":{"id":"3dc153be303440df","repo":"elastic/elasticsearch","slug":"circle","errorCode":null,"errorMessage":"circle [","messagePattern":"circle \\[","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/geo/src/main/java/org/elasticsearch/geometry/utils/CircleUtils.java","lineNumber":38,"sourceCode":"    static final int CIRCLE_TO_POLYGON_MINIMUM_NUMBER_OF_SIDES = 4;\n    static final int CIRCLE_TO_POLYGON_MAXIMUM_NUMBER_OF_SIDES = 1000;\n\n    private CircleUtils() {}\n\n    /**\n     * Makes an n-gon, centered at the provided circle's center, and each vertex approximately\n     * {@link Circle#getRadiusMeters()} away from the center.\n     *\n     * It throws an IllegalArgumentException if the circle contains a pole.\n     *\n     * This does not split the polygon across the date-line. Relies on org.elasticsearch.index.mapper.GeoShapeIndexer to\n     * split prepare polygon for indexing.\n     *\n     * Adapted from from org.apache.lucene.tests.geo.GeoTestUtil\n     * */\n    public static Polygon createRegularGeoShapePolygon(Circle circle, int gons) {\n        if (slowHaversin(circle.getLat(), circle.getLon(), 90, 0) < circle.getRadiusMeters()) {\n            throw new IllegalArgumentException(\n                \"circle [\" + circle.toString() + \"] contains the north pole. \" + \"It cannot be translated to a polygon\"\n            );\n        }\n        if (slowHaversin(circle.getLat(), circle.getLon(), -90, 0) < circle.getRadiusMeters()) {\n            throw new IllegalArgumentException(\n                \"circle [\" + circle.toString() + \"] contains the south pole. \" + \"It cannot be translated to a polygon\"\n            );\n        }\n        double[][] result = new double[2][];\n        result[0] = new double[gons + 1];\n        result[1] = new double[gons + 1];\n        for (int i = 0; i < gons; i++) {\n            // make sure we do not start at angle 0 or we have issues at the poles\n            double angle = i * (360.0 / gons);\n            double x = Math.cos(Math.toRadians(angle));\n            double y = Math.sin(Math.toRadians(angle));\n            double factor = 2.0;\n            double step = 1.0;","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/geo/src/main/java/org/elasticsearch/geometry/utils/CircleUtils.java#L20-L56","documentation":"Thrown by CircleUtils.createRegularGeoShapePolygon when the input Circle encloses the north pole — i.e. the haversine distance from the circle's center to (lat=90, lon=0) is less than the circle's radius. The n-gon approximation used by this method cannot represent a polygon that contains a pole, so it refuses rather than producing a malformed shape.","triggerScenarios":"Calling `CircleUtils.createRegularGeoShapePolygon(circle, gons)` where `slowHaversin(circle.getLat(), circle.getLon(), 90, 0) < circle.getRadiusMeters()`. Typically a circle centered at high northern latitude with a large radius.","commonSituations":"User-drawn circles near the poles (e.g. Arctic coverage); radius values in the wrong unit (meters expected, miles or km supplied makes the radius ~1000x too large); circles generated from bounding boxes that happen to enclose the pole.","solutions":["Reduce the radius so it no longer reaches the pole, or move the center away from the pole.","Confirm radius is in meters (getRadiusMeters) — a unit mismatch is the most frequent cause.","If pole-containing coverage is genuinely required, represent it as a different geometry (e.g. a polygon that explicitly includes the pole) rather than via this n-gon helper."],"exampleFix":"// before\nCircle c = new Circle(80, 0, 2_000_000); // 2000 km from lat 80 reaches the pole\nPolygon p = CircleUtils.createRegularGeoShapePolygon(c, 64); // throws\n\n// after\nCircle c = new Circle(80, 0, 500_000); // smaller radius stays clear of the pole\nPolygon p = CircleUtils.createRegularGeoShapePolygon(c, 64);","handlingStrategy":"validation","validationCode":"double distToNorthPole = slowHaversin(circle.getLat(), circle.getLon(), 90, 0);\nif (distToNorthPole < circle.getRadiusMeters()) {\n    throw new IllegalArgumentException(\"circle reaches north pole; reduce radius or move center\");\n}\nreturn CircleUtils.createRegularGeoShapePolygon(circle, gons);","typeGuard":null,"tryCatchPattern":"try {\n    return CircleUtils.createRegularGeoShapePolygon(circle, gons);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"north pole\")) {\n        // reduce radius to just below the pole distance and retry, or skip\n    }\n    throw e;\n}","preventionTips":["Verify radius units are meters — unit mismatch is the most common cause.","For circles near lat > 60, pre-check the pole distance before calling createRegularGeoShapePolygon.","Use a different geometry representation for genuine polar coverage."],"tags":["geometry","circle","polygon","pole","geographic","radius","libs-geo"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}