elastic/elasticsearch · error · IllegalArgumentException

out of range input

Error message

 out of range input

What it means

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.

Source

Thrown at libs/h3/src/main/java/org/elasticsearch/h3/FaceIJK.java:690

    /**
     * compute the corresponding H3Index.
     * @param res The cell resolution.
     * @param face The face.
     * @param coord The CoordIJK.
     * @return The encoded H3Index
     */
    static long faceIjkToH3(int res, int face, CoordIJK coord) {
        // initialize the index
        long h = H3Index.H3_INIT;
        h = H3Index.H3_set_mode(h, Constants.H3_CELL_MODE);
        h = H3Index.H3_set_resolution(h, res);

        // check for res 0/base cell
        if (res == 0) {
            if (coord.i > MAX_FACE_COORD || coord.j > MAX_FACE_COORD || coord.k > MAX_FACE_COORD) {
                // out of range input
                throw new IllegalArgumentException(" out of range input");
            }
            return H3Index.H3_set_base_cell(h, BaseCells.getBaseCell(face, coord));
        }

        // we need to find the correct base cell CoordIJK for this H3 index;
        // start with the passed in face and resolution res ijk coordinates
        // in that face's coordinate system

        // build the H3Index from finest res up
        // adjust r for the fact that the res 0 base cell offsets the indexing
        // digits
        final CoordIJK scratch = new CoordIJK(0, 0, 0);
        for (int r = res; r > 0; r--) {
            final int lastI = coord.i;
            final int lastJ = coord.j;
            final int lastK = coord.k;
            if (H3Index.isResolutionClassIII(r)) {
                // rotate ccw

View on GitHub (pinned to db6a809a66)

Solutions

1. Use H3.geoToH3(lat, lng, 0) for res-0 indexes; it validates resolution and normalizes coordinates before reaching this path.
2. If calling faceIjkToH3 directly in tests/internal code, ensure the CoordIJK is normalized (each component in [0, MAX_FACE_COORD]).
3. Treat this in production as a sign of upstream corruption of an H3 long or coordinate and re-derive the index from lat/lng.

Example fix

// before (internal/test misuse)
FaceIJK.faceIjkToH3(0, face, new CoordIJK(7, 0, 0)); // throws: out of range input

// after
long cell = H3.geoToH3(lat, lng, 0); // public, normalized

// For public callers: prefer geoToH3; never call faceIjkToH3 directly.
static long safeRes0(double lat, double lng) {
    return org.elasticsearch.h3.H3.geoToH3(lat, lng, 0);
}

// faceIjkToH3 is internal; treat any throw here as an internal-invariant break,
// fail fast and report rather than retry.
try {
    return FaceIJK.faceIjkToH3(0, face, coord);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("internal H3 encode failure at res 0", e);
}

When it happens

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

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

Related errors

• Illegal base cell
• Undefined error checking for neighbors
• Bootstrapping cluster secrets in file settings is not suppor
• Elasticsearch could not determine the origin of JVM option [
• Input is a base cell

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