elastic/elasticsearch · error · IllegalArgumentException

Invalid child resolution [{}]

Error message

Invalid child resolution [{}]

What it means

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.

Source

Thrown at libs/h3/src/main/java/org/elasticsearch/h3/H3.java:455

     */
    public static boolean areNeighborCells(long origin, long destination) {
        return HexRing.areNeighbours(origin, destination);
    }

    /**
     * h3ToChildrenSize returns the exact number of children for a cell at a
     * given child resolution.
     *
     * @param h3         H3Index to find the number of children of
     * @param childRes  The child resolution you're interested in
     *
     * @return long      Exact number of children (handles hexagons and pentagons
     *                  correctly)
     */
    public static long h3ToChildrenSize(long h3, int childRes) {
        final int parentRes = H3Index.H3_get_resolution(h3);
        if (childRes <= parentRes || childRes > MAX_H3_RES) {
            throw new IllegalArgumentException("Invalid child resolution [" + childRes + "]");
        }
        final int n = childRes - parentRes;
        if (H3Index.H3_is_pentagon(h3)) {
            return (1L + 5L * (_ipow(7, n) - 1L) / 6L);
        } else {
            return _ipow(7, n);
        }
    }

    /**
     * h3ToChildrenSize returns the exact number of children for a h3 affress at a
     * given child resolution.
     *
     * @param h3Address  H3 address to find the number of children of
     * @param childRes  The child resolution you're interested in
     *
     * @return int      Exact number of children (handles hexagons and pentagons
     *                  correctly)

View on GitHub (pinned to db6a809a66)

Solutions

1. Validate parentRes = getResolution(cell) and require parentRes < childRes <= H3.MAX_H3_RES before calling.
2. Clamp or reject user-supplied childRes upstream; surface a clear error to the user rather than relying on the library's message.
3. If you only need immediate children count, use the single-arg h3ToChildrenSize(cell).

Example fix

// before
long n = H3.h3ToChildrenSize(cell, H3.getResolution(cell)); // throws: childRes == parentRes

// after
int parentRes = H3.getResolution(cell);
if (childRes <= parentRes || childRes > H3.MAX_H3_RES) {
    throw new IllegalArgumentException("childRes must be in (" + parentRes + ", 15]");
}
long n = H3.h3ToChildrenSize(cell, childRes);

static long safeChildrenSize(long h3, int childRes) {
    int parent = org.elasticsearch.h3.H3.getResolution(h3);
    if (childRes <= parent || childRes > org.elasticsearch.h3.H3.MAX_H3_RES) {
        throw new IllegalArgumentException(
            "childRes must be in (" + parent + ", " + org.elasticsearch.h3.H3.MAX_H3_RES + "]");
    }
    return org.elasticsearch.h3.H3.h3ToChildrenSize(h3, childRes);
}

static boolean validChildRes(long h3, int childRes) {
    int parent = org.elasticsearch.h3.H3.getResolution(h3);
    return childRes > parent && childRes <= org.elasticsearch.h3.H3.MAX_H3_RES;
}

try {
    return H3.h3ToChildrenSize(h3, childRes);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid child resolution")) {
        throw new IllegalArgumentException("bad childRes " + childRes + " for res "
            + H3.getResolution(h3) + " cell", e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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].

Related errors

• Input is a base cell
• Resolution overflow
• invalid child position
• resolution [{}] is out of range (must be 0 <= res <= 15)
• Illegal base cell

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/68a297a05e9045b2. Report an issue: GitHub.