{"record":{"id":"68a297a05e9045b2","repo":"elastic/elasticsearch","slug":"invalid-child-resolution","errorCode":null,"errorMessage":"Invalid child resolution [{}]","messagePattern":"Invalid child resolution \\[(.+?)\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/h3/src/main/java/org/elasticsearch/h3/H3.java","lineNumber":455,"sourceCode":"     */\n    public static boolean areNeighborCells(long origin, long destination) {\n        return HexRing.areNeighbours(origin, destination);\n    }\n\n    /**\n     * h3ToChildrenSize returns the exact number of children for a cell at a\n     * given child resolution.\n     *\n     * @param h3         H3Index to find the number of children of\n     * @param childRes  The child resolution you're interested in\n     *\n     * @return long      Exact number of children (handles hexagons and pentagons\n     *                  correctly)\n     */\n    public static long h3ToChildrenSize(long h3, int childRes) {\n        final int parentRes = H3Index.H3_get_resolution(h3);\n        if (childRes <= parentRes || childRes > MAX_H3_RES) {\n            throw new IllegalArgumentException(\"Invalid child resolution [\" + childRes + \"]\");\n        }\n        final int n = childRes - parentRes;\n        if (H3Index.H3_is_pentagon(h3)) {\n            return (1L + 5L * (_ipow(7, n) - 1L) / 6L);\n        } else {\n            return _ipow(7, n);\n        }\n    }\n\n    /**\n     * h3ToChildrenSize returns the exact number of children for a h3 affress at a\n     * given child resolution.\n     *\n     * @param h3Address  H3 address to find the number of children of\n     * @param childRes  The child resolution you're interested in\n     *\n     * @return int      Exact number of children (handles hexagons and pentagons\n     *                  correctly)","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/h3/src/main/java/org/elasticsearch/h3/H3.java#L437-L473","documentation":"Thrown by H3.h3ToChildrenSize(long, int) when childRes is not strictly greater than the parent's resolution and not above MAX_H3_RES. A child resolution must be a finer level than the parent (parentRes < childRes <= 15); equal, lower, or >15 values are rejected because the children-count formula (7^n or the pentagon variant) would be meaningless.","triggerScenarios":"Calling h3ToChildrenSize(cell, childRes) with childRes <= getResolution(cell) (e.g. asking how many children a res-5 cell has at res 3) or childRes > 15. The string overload delegates and throws identically.","commonSituations":"User inputs a target resolution that is the same as or coarser than the cell; off-by-one where childRes is computed as parentRes instead of parentRes+1; untrusted resolution values not clamped to [parentRes+1, 15].","solutions":["Validate parentRes = getResolution(cell) and require parentRes < childRes <= H3.MAX_H3_RES before calling.","Clamp or reject user-supplied childRes upstream; surface a clear error to the user rather than relying on the library's message.","If you only need immediate children count, use the single-arg h3ToChildrenSize(cell)."],"exampleFix":"// before\nlong n = H3.h3ToChildrenSize(cell, H3.getResolution(cell)); // throws: childRes == parentRes\n\n// after\nint parentRes = H3.getResolution(cell);\nif (childRes <= parentRes || childRes > H3.MAX_H3_RES) {\n    throw new IllegalArgumentException(\"childRes must be in (\" + parentRes + \", 15]\");\n}\nlong n = H3.h3ToChildrenSize(cell, childRes);","handlingStrategy":"validation","validationCode":"static long safeChildrenSize(long h3, int childRes) {\n    int parent = org.elasticsearch.h3.H3.getResolution(h3);\n    if (childRes <= parent || childRes > org.elasticsearch.h3.H3.MAX_H3_RES) {\n        throw new IllegalArgumentException(\n            \"childRes must be in (\" + parent + \", \" + org.elasticsearch.h3.H3.MAX_H3_RES + \"]\");\n    }\n    return org.elasticsearch.h3.H3.h3ToChildrenSize(h3, childRes);\n}","typeGuard":"static boolean validChildRes(long h3, int childRes) {\n    int parent = org.elasticsearch.h3.H3.getResolution(h3);\n    return childRes > parent && childRes <= org.elasticsearch.h3.H3.MAX_H3_RES;\n}","tryCatchPattern":"try {\n    return H3.h3ToChildrenSize(h3, childRes);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Invalid child resolution\")) {\n        throw new IllegalArgumentException(\"bad childRes \" + childRes + \" for res \"\n            + H3.getResolution(h3) + \" cell\", e);\n    }\n    throw e;\n}","preventionTips":["Require parentRes < childRes <= MAX_H3_RES at the call site.","Clamp user-supplied resolutions to (parentRes, 15].","Use the single-arg h3ToChildrenSize when you only need immediate children."],"tags":["h3","child","resolution","validation"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}