elastic/elasticsearch · error · IllegalArgumentException

Illegal base cell

Error message

Illegal base cell

What it means

Thrown by BaseCells.getBaseFaceIJK when the supplied base cell number is outside the valid range [0, NUM_BASE_CELLS). H3 has 122 base cells (resolution-0 cells); a negative or >=122 value cannot index the internal baseCellData table. This is a low-level, package-private helper used during index encode/decode, not part of the public H3 API.

Source

Thrown at libs/h3/src/main/java/org/elasticsearch/h3/BaseCells.java:591

    /**
     *  Return whether or not the indicated base cell is a pentagon.
     */
    public static boolean isBaseCellPentagon(int baseCell) {
        if (baseCell < 0 || baseCell >= Constants.NUM_BASE_CELLS) {  // LCOV_EXCL_BR_LINE
            // Base cells less than zero can not be represented in an index
            return false;
        }
        return baseCellData[baseCell].isPentagon;
    }

    /**
     *  Return whether or not the indicated base cell is a pentagon.
     */
    public static FaceIJK getBaseFaceIJK(int baseCell) {
        if (baseCell < 0 || baseCell >= Constants.NUM_BASE_CELLS) {  // LCOV_EXCL_BR_LINE
            // Base cells less than zero can not be represented in an index
            throw new IllegalArgumentException("Illegal base cell");
        }
        BaseCellData cellData = baseCellData[baseCell];
        return new FaceIJK(cellData.homeFace, new CoordIJK(cellData.homeI, cellData.homeJ, cellData.homeK));
    }

    /** Find base cell given a face and a CoordIJK.
     *
     * Given the face number and a resolution 0 ijk+ coordinate in that face's
     * face-centered ijk coordinate system, return the base cell located at that
     * coordinate.
     *
     * Valid ijk+ lookup coordinates are from (0, 0, 0) to (2, 2, 2).
     */
    public static int getBaseCell(int face, CoordIJK coord) {
        return faceIjkBaseCells[face][coord.i][coord.j][coord.k].baseCell;
    }

    /** Find base cell given a face and a CoordIJK.

View on GitHub (pinned to db6a809a66)

Solutions

1. Do not call BaseCells directly; use H3 public methods (geoToH3, h3ToParent, etc.) which validate inputs.
2. If you hold a raw long from an external source, gate it with H3.h3IsValid(h3) before any operation that could touch base-cell internals.
3. Re-derive the index from coordinates via H3.geoToH3 rather than trusting an unverified long.

Example fix

// before
long unknown = parseFromWire();
FaceIJK fijk = BaseCells.getBaseFaceIJK(H3Index.H3_get_base_cell(unknown)); // may throw

// after
long unknown = parseFromWire();
if (H3.h3IsValid(unknown) == false) {
    throw new IllegalArgumentException("not a valid H3 index: " + unknown);
}
FaceIJK fijk = BaseCells.getBaseFaceIJK(H3Index.H3_get_base_cell(unknown));

static boolean validBaseCell(int bc) {
    return bc >= 0 && bc < org.elasticsearch.h3.Constants.NUM_BASE_CELLS;
}
// Usage: avoid calling BaseCells directly; gate raw longs first.
static boolean safeToUse(long h3) {
    return org.elasticsearch.h3.H3.h3IsValid(h3);
}

static boolean isUsableH3(long h3) {
    return org.elasticsearch.h3.H3.h3IsValid(h3);
}

// Prefer not to reach BaseCells at all; if you must, wrap it.
try {
    return BaseCells.getBaseFaceIJK(bc);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("invalid base cell " + bc + ": " + e.getMessage(), e);
}

When it happens

Trigger: Calling BaseCells.getBaseFaceIJK (or an internal path that calls it) with a base-cell id parsed from a corrupt or non-H3 long whose base-cell field is out of range. Direct external calls are uncommon; the public API validates and masks this before reaching here.

Common situations: Passing a hand-crafted or bit-corrupted H3 long whose base-cell nibble is invalid; version skew where a long encoded by a different/incompatible H3 build is fed in; internal testing of edge indexes.

Related errors

• Invalid base cell looking for neighbor
• out of range input
• Input is a base cell
• invalid child position
• invalid ring position

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