{"record":{"id":"6e435d13fc04eff2","repo":"elastic/elasticsearch","slug":"resolution-overflow","errorCode":null,"errorMessage":"Resolution overflow","messagePattern":"Resolution overflow","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/h3/src/main/java/org/elasticsearch/h3/H3.java","lineNumber":264,"sourceCode":"        }\n        return children;\n    }\n\n    /**\n     * Transforms a list of H3 indexes in long form to a list of H3\n     * indexes in string form.\n     */\n    public static String[] h3ToChildren(String h3Address) {\n        return h3ToStringList(h3ToChildren(stringToH3(h3Address)));\n    }\n\n    /**\n     * Returns the child cell at the given position\n     */\n    public static long childPosToH3(long h3, int childPos) {\n        final int childrenRes = H3Index.H3_get_resolution(h3) + 1;\n        if (childrenRes > MAX_H3_RES) {\n            throw new IllegalArgumentException(\"Resolution overflow\");\n        }\n        final long childH = H3Index.H3_set_resolution(h3, childrenRes);\n        if (childPos == 0) {\n            return H3Index.H3_set_index_digit(childH, childrenRes, CoordIJK.Direction.CENTER_DIGIT.digit());\n        }\n        final boolean isPentagon = isPentagon(h3);\n        final int maxPos = isPentagon ? 5 : 6;\n        if (childPos < 0 || childPos > maxPos) {\n            throw new IllegalArgumentException(\"invalid child position\");\n        }\n        if (isPentagon) {\n            // Pentagon skip digit (position) is the number 1, therefore we add one\n            // to the current position.\n            return H3Index.H3_set_index_digit(childH, childrenRes, childPos + 1);\n        } else {\n            return H3Index.H3_set_index_digit(childH, childrenRes, childPos);\n        }\n    }","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/h3/src/main/java/org/elasticsearch/h3/H3.java#L246-L282","documentation":"Thrown by H3.childPosToH3 when the input index is already at MAX_H3_RES (15). Computing a child requires resolution+1; 15+1 exceeds the maximum, so no child can exist. The string overload propagates the same exception.","triggerScenarios":"Calling childPosToH3(cell, pos) (or h3ToChildren/h3ToChildren(address) which call it internally) on a res-15 index. Also reached via H3.hexRing -> hexRingPosToH3 path indirectly when chained incorrectly.","commonSituations":"General-purpose code that unconditionally subdivides cells without checking the current resolution; consuming res-15 fine-grained cells and trying to refine them further; recursive algorithms lacking a res-15 base case.","solutions":["Gate child computation with H3.getResolution(h3) < H3.MAX_H3_RES before calling childPosToH3 or h3ToChildren.","Treat res-15 cells as leaves in any recursive subdivision.","Use h3ToChildrenSize(h3) first (which throws Invalid child resolution at res 15) only after the resolution check, to size outputs."],"exampleFix":"// before\nlong[] kids = H3.h3ToChildren(cell); // throws Resolution overflow if cell is res 15\n\n// after\nlong[] kids = H3.getResolution(cell) < H3.MAX_H3_RES\n    ? H3.h3ToChildren(cell)\n    : new long[0];","handlingStrategy":"validation","validationCode":"static boolean canRefine(long h3) {\n    return org.elasticsearch.h3.H3.getResolution(h3) < org.elasticsearch.h3.H3.MAX_H3_RES;\n}\nstatic long[] safeChildren(long h3) {\n    return canRefine(h3) ? org.elasticsearch.h3.H3.h3ToChildren(h3) : new long[0];\n}","typeGuard":"static boolean isRefinable(long h3) {\n    return org.elasticsearch.h3.H3.getResolution(h3) < org.elasticsearch.h3.H3.MAX_H3_RES;\n}","tryCatchPattern":"try {\n    return H3.childPosToH3(h3, pos);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().equals(\"Resolution overflow\")) return -1; // leaf\n    throw e;\n}","preventionTips":["Gate every refine/children call with getResolution < MAX_H3_RES.","Make res-15 a leaf in recursive subdivision.","Centralize the resolution guard so child-count and child-iteration share it."],"tags":["h3","child","resolution","overflow"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}