{"record":{"id":"35df42c9f07da1e6","repo":"elastic/elasticsearch","slug":"out-of-range-input","errorCode":null,"errorMessage":" out of range input","messagePattern":" out of range input","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/h3/src/main/java/org/elasticsearch/h3/FaceIJK.java","lineNumber":690,"sourceCode":"\n    /**\n     * compute the corresponding H3Index.\n     * @param res The cell resolution.\n     * @param face The face.\n     * @param coord The CoordIJK.\n     * @return The encoded H3Index\n     */\n    static long faceIjkToH3(int res, int face, CoordIJK coord) {\n        // initialize the index\n        long h = H3Index.H3_INIT;\n        h = H3Index.H3_set_mode(h, Constants.H3_CELL_MODE);\n        h = H3Index.H3_set_resolution(h, res);\n\n        // check for res 0/base cell\n        if (res == 0) {\n            if (coord.i > MAX_FACE_COORD || coord.j > MAX_FACE_COORD || coord.k > MAX_FACE_COORD) {\n                // out of range input\n                throw new IllegalArgumentException(\" out of range input\");\n            }\n            return H3Index.H3_set_base_cell(h, BaseCells.getBaseCell(face, coord));\n        }\n\n        // we need to find the correct base cell CoordIJK for this H3 index;\n        // start with the passed in face and resolution res ijk coordinates\n        // in that face's coordinate system\n\n        // build the H3Index from finest res up\n        // adjust r for the fact that the res 0 base cell offsets the indexing\n        // digits\n        final CoordIJK scratch = new CoordIJK(0, 0, 0);\n        for (int r = res; r > 0; r--) {\n            final int lastI = coord.i;\n            final int lastJ = coord.j;\n            final int lastK = coord.k;\n            if (H3Index.isResolutionClassIII(r)) {\n                // rotate ccw","sourceCodeStart":672,"sourceCodeEnd":708,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/h3/src/main/java/org/elasticsearch/h3/FaceIJK.java#L672-L708","documentation":"Thrown by FaceIJK.faceIjkToH3 at resolution 0 when any of the ijk face-coordinate components exceeds MAX_FACE_COORD. At res 0 the coordinate must map to a base cell; an out-of-range coordinate cannot be looked up in the faceIjkBaseCells table. This is an internal encode path invoked by geoToH3 after coordinate normalization.","triggerScenarios":"Reached only when the internal face-centered ijk coordinate produced during encoding of a res-0 index has a component beyond the allowed [0, MAX_FACE_COORD] band. With public geoToH3 input this is effectively unreachable because Vec3d.geoToH3 normalizes coordinates first; it indicates either an internal invariant break or a directly invoked internal method with bad coords.","commonSituations":"Direct internal testing of faceIjkToH3 with manually constructed CoordIJK; a corrupted/unnormalized coordinate passed by another internal routine; not a normal user-facing condition for valid lat/lng input.","solutions":["Use H3.geoToH3(lat, lng, 0) for res-0 indexes; it validates resolution and normalizes coordinates before reaching this path.","If calling faceIjkToH3 directly in tests/internal code, ensure the CoordIJK is normalized (each component in [0, MAX_FACE_COORD]).","Treat this in production as a sign of upstream corruption of an H3 long or coordinate and re-derive the index from lat/lng."],"exampleFix":"// before (internal/test misuse)\nFaceIJK.faceIjkToH3(0, face, new CoordIJK(7, 0, 0)); // throws: out of range input\n\n// after\nlong cell = H3.geoToH3(lat, lng, 0); // public, normalized","handlingStrategy":"validation","validationCode":"// For public callers: prefer geoToH3; never call faceIjkToH3 directly.\nstatic long safeRes0(double lat, double lng) {\n    return org.elasticsearch.h3.H3.geoToH3(lat, lng, 0);\n}","typeGuard":null,"tryCatchPattern":"// faceIjkToH3 is internal; treat any throw here as an internal-invariant break,\n// fail fast and report rather than retry.\ntry {\n    return FaceIJK.faceIjkToH3(0, face, coord);\n} catch (IllegalArgumentException e) {\n    throw new IllegalStateException(\"internal H3 encode failure at res 0\", e);\n}","preventionTips":["Route all index creation through H3.geoToH3.","Keep internal CoordIJK components within [0, MAX_FACE_COORD] in unit tests.","Do not feed hand-built coordinates into faceIjkToH3 outside tests."],"tags":["h3","internal","coordinate","encode"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}