{"record":{"id":"b7a3ef1a5631b4d3","repo":"PHPOffice/PhpSpreadsheet","slug":"unrecognized-token-02x-in-formula","errorCode":null,"errorMessage":"Unrecognized token %02X in formula","messagePattern":"Unrecognized token %02X in formula","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Reader\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Reader/Xls.php","lineNumber":4774,"sourceCode":"                $name = 'tArea3d';\n                $size = 11;\n\n                try {\n                    // offset: 1; size: 2; index to REF entry\n                    $sheetRange = $this->readSheetRangeByRefIndex(self::getUInt2d($formulaData, 1));\n                    // offset: 3; size: 8; cell address\n                    $cellRangeAddress = Xls\\Biff8::readBIFF8CellRangeAddress(substr($formulaData, 3, 8));\n\n                    $data = \"$sheetRange!$cellRangeAddress\";\n                } catch (PhpSpreadsheetException) {\n                    // deleted sheet reference\n                    $data = '#REF!';\n                }\n\n                break;\n                // Unknown cases    // don't know how to deal with\n            default:\n                throw new Exception('Unrecognized token ' . sprintf('%02X', $id) . ' in formula');\n        }\n\n        return [\n            'id' => $id,\n            'name' => $name,\n            'size' => $size,\n            'data' => $data,\n        ];\n    }\n\n    /**\n     * Get a sheet range like Sheet1:Sheet3 from REF index\n     * Note: If there is only one sheet in the range, one gets e.g Sheet1\n     * It can also happen that the REF structure uses the -1 (FFFF) code to indicate deleted sheets,\n     * in which case an Exception is thrown.\n     */\n    protected function readSheetRangeByRefIndex(int $index): string|false\n    {","sourceCodeStart":4756,"sourceCodeEnd":4792,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Reader/Xls.php#L4756-L4792","documentation":"The generic fallback of the formula token interpreter: the token id byte at the current stream position matches no known BIFF token class, so parsing cannot continue and the whole load aborts. The message interpolates the offending id in hex.","triggerScenarios":"Corrupted FORMULA/SHRFMLA records where the token stream got shifted or overwritten; BIFF variants or undocumented tokens from other spreadsheet applications that reuse the .xls container.","commonSituations":"Upload endpoints accepting arbitrary .xls files; files damaged in storage or transfer; exports from unconventional tools that are 'almost BIFF8'.","solutions":["Repair the file in Excel (Open and Repair) or round-trip it through LibreOffice, then load the result","Log the hex token id from the exception message and the sheet/cell context to identify the producer","If you control the producer, fix or avoid the nonstandard token; otherwise fall back to a values-only load"],"exampleFix":"// before\n$spreadsheet = IOFactory::load('weird.xls'); // Unrecognized token 7F in formula\n\n// after: degrade gracefully for unparseable formulas\ntry {\n    $spreadsheet = IOFactory::load('weird.xls');\n} catch (\\PhpOffice\\PhpSpreadsheet\\Reader\\Exception $e) {\n    $reader = new \\PhpOffice\\PhpSpreadsheet\\Reader\\Xls();\n    $reader->setReadDataOnly(true);\n    $spreadsheet = $reader->load('weird.xls');\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $spreadsheet = IOFactory::load($path);\n} catch (\\PhpOffice\\PhpSpreadsheet\\Reader\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Unrecognized token')) {\n        // capture the hex id from the message for diagnostics; request repaired file\n    }\n}","preventionTips":["Run Excel 'Open and Repair' (or LibreOffice round-trip) on suspicious uploads","Keep uploads in binary-safe storage; avoid re-encoding file bytes","Log exception messages verbatim — the token id is the key clue"],"tags":["xls","formula","biff","token-parser","phpspreadsheet"],"backgroundTag":"malformed-formula-token","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}