elastic/elasticsearch · error · IllegalArgumentException

Input is a base cell

Error message

Input is a base cell

What it means

Thrown by H3.h3ToParent when the input index is already at resolution 0. Resolution-0 cells are the 122 base cells and have no parent; requesting one is meaningless, so the method refuses rather than producing a nonsensical result. The string overload re-throws the same exception after converting via stringToH3.

Source

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

     * Find the H3 index of the resolution <code>res</code> cell containing the lat/lon (in degrees)
     *
     * @param lat Latitude in degrees.
     * @param lng Longitude in degrees.
     * @param res Resolution, 0 &lt;= res &lt;= 15
     * @return The H3 index.
     * @throws IllegalArgumentException Latitude, longitude, or resolution is out of range.
     */
    public static String geoToH3Address(double lat, double lng, int res) {
        return h3ToString(geoToH3(lat, lng, res));
    }

    /**
     * Returns the parent of the given index.
     */
    public static long h3ToParent(long h3) {
        int childRes = H3Index.H3_get_resolution(h3);
        if (childRes == 0) {
            throw new IllegalArgumentException("Input is a base cell");
        }
        long parentH = H3Index.H3_set_resolution(h3, childRes - 1);
        return H3Index.H3_set_index_digit(parentH, childRes, H3Index.H3_DIGIT_MASK);
    }

    /**
     * Returns the parent of the given index.
     */
    public static String h3ToParent(String h3Address) {
        long parent = h3ToParent(stringToH3(h3Address));
        return h3ToString(parent);
    }

    /**
     * Returns the children of the given index.
     */
    public static long[] h3ToChildren(long h3) {
        final long[] children = new long[h3ToChildrenSize(h3)];

View on GitHub (pinned to db6a809a66)

Solutions

1. Check H3.getResolution(h3) > 0 before calling h3ToParent, and stop the walk at res 0.
2. If you need a coarse ancestor, query h3ToParent only for resolutions > 0 and treat res 0 as the root.
3. Validate user-supplied indexes with getResolution and reject/clamp res-0 input upstream.

Example fix

// before
long parent = H3.h3ToParent(cell); // throws if cell is res 0

// after
long parent = H3.getResolution(cell) > 0 ? H3.h3ToParent(cell) : cell;

static long safeParent(long h3) {
    if (org.elasticsearch.h3.H3.getResolution(h3) == 0) {
        throw new IllegalArgumentException("res-0 cell has no parent: " + h3);
    }
    return org.elasticsearch.h3.H3.h3ToParent(h3);
}

static boolean hasParent(long h3) {
    return org.elasticsearch.h3.H3.getResolution(h3) > 0;
}

try {
    return H3.h3ToParent(h3);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Input is a base cell")) return h3; // already root
    throw e;
}

When it happens

Trigger: Calling H3.h3ToParent(h3) or H3.h3ToParent(address) on a res-0 index (e.g. one returned by getLongRes0Cells, or geoToH3(lat,lng,0)). Also when iterating parents in a loop that does not stop before reaching res 0.

Common situations: Writing a loop that walks up the hierarchy (h3ToParent repeatedly) without a base case; consuming an index whose resolution you did not check; mixing res-0 cells from a polar/overview dataset into a parent-walk routine.

Related errors

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

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