{"record":{"id":"26af24239e5cdfb9","repo":"elastic/elasticsearch","slug":"illegal-base-cell","errorCode":null,"errorMessage":"Illegal base cell","messagePattern":"Illegal base cell","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/h3/src/main/java/org/elasticsearch/h3/BaseCells.java","lineNumber":591,"sourceCode":"\n    /**\n     *  Return whether or not the indicated base cell is a pentagon.\n     */\n    public static boolean isBaseCellPentagon(int baseCell) {\n        if (baseCell < 0 || baseCell >= Constants.NUM_BASE_CELLS) {  // LCOV_EXCL_BR_LINE\n            // Base cells less than zero can not be represented in an index\n            return false;\n        }\n        return baseCellData[baseCell].isPentagon;\n    }\n\n    /**\n     *  Return whether or not the indicated base cell is a pentagon.\n     */\n    public static FaceIJK getBaseFaceIJK(int baseCell) {\n        if (baseCell < 0 || baseCell >= Constants.NUM_BASE_CELLS) {  // LCOV_EXCL_BR_LINE\n            // Base cells less than zero can not be represented in an index\n            throw new IllegalArgumentException(\"Illegal base cell\");\n        }\n        BaseCellData cellData = baseCellData[baseCell];\n        return new FaceIJK(cellData.homeFace, new CoordIJK(cellData.homeI, cellData.homeJ, cellData.homeK));\n    }\n\n    /** Find base cell given a face and a CoordIJK.\n     *\n     * Given the face number and a resolution 0 ijk+ coordinate in that face's\n     * face-centered ijk coordinate system, return the base cell located at that\n     * coordinate.\n     *\n     * Valid ijk+ lookup coordinates are from (0, 0, 0) to (2, 2, 2).\n     */\n    public static int getBaseCell(int face, CoordIJK coord) {\n        return faceIjkBaseCells[face][coord.i][coord.j][coord.k].baseCell;\n    }\n\n    /** Find base cell given a face and a CoordIJK.","sourceCodeStart":573,"sourceCodeEnd":609,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/h3/src/main/java/org/elasticsearch/h3/BaseCells.java#L573-L609","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Do not call BaseCells directly; use H3 public methods (geoToH3, h3ToParent, etc.) which validate inputs.","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.","Re-derive the index from coordinates via H3.geoToH3 rather than trusting an unverified long."],"exampleFix":"// before\nlong unknown = parseFromWire();\nFaceIJK fijk = BaseCells.getBaseFaceIJK(H3Index.H3_get_base_cell(unknown)); // may throw\n\n// after\nlong unknown = parseFromWire();\nif (H3.h3IsValid(unknown) == false) {\n    throw new IllegalArgumentException(\"not a valid H3 index: \" + unknown);\n}\nFaceIJK fijk = BaseCells.getBaseFaceIJK(H3Index.H3_get_base_cell(unknown));","handlingStrategy":"validation","validationCode":"static boolean validBaseCell(int bc) {\n    return bc >= 0 && bc < org.elasticsearch.h3.Constants.NUM_BASE_CELLS;\n}\n// Usage: avoid calling BaseCells directly; gate raw longs first.\nstatic boolean safeToUse(long h3) {\n    return org.elasticsearch.h3.H3.h3IsValid(h3);\n}","typeGuard":"static boolean isUsableH3(long h3) {\n    return org.elasticsearch.h3.H3.h3IsValid(h3);\n}","tryCatchPattern":"// Prefer not to reach BaseCells at all; if you must, wrap it.\ntry {\n    return BaseCells.getBaseFaceIJK(bc);\n} catch (IllegalArgumentException e) {\n    throw new IllegalArgumentException(\"invalid base cell \" + bc + \": \" + e.getMessage(), e);\n}","preventionTips":["Use the public H3 API; do not call BaseCells from application code.","Validate every external long with H3.h3IsValid at the trust boundary.","Re-derive indexes from lat/lng rather than parsing raw longs."],"tags":["h3","internal","base-cell","validation"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}