PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Reader\Exception

Unrecognized token %02X in formula

Error message

Unrecognized token %02X in formula

What it means

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.

Source

Thrown at src/PhpSpreadsheet/Reader/Xls.php:4774

                $name = 'tArea3d';
                $size = 11;

                try {
                    // offset: 1; size: 2; index to REF entry
                    $sheetRange = $this->readSheetRangeByRefIndex(self::getUInt2d($formulaData, 1));
                    // offset: 3; size: 8; cell address
                    $cellRangeAddress = Xls\Biff8::readBIFF8CellRangeAddress(substr($formulaData, 3, 8));

                    $data = "$sheetRange!$cellRangeAddress";
                } catch (PhpSpreadsheetException) {
                    // deleted sheet reference
                    $data = '#REF!';
                }

                break;
                // Unknown cases    // don't know how to deal with
            default:
                throw new Exception('Unrecognized token ' . sprintf('%02X', $id) . ' in formula');
        }

        return [
            'id' => $id,
            'name' => $name,
            'size' => $size,
            'data' => $data,
        ];
    }

    /**
     * Get a sheet range like Sheet1:Sheet3 from REF index
     * Note: If there is only one sheet in the range, one gets e.g Sheet1
     * It can also happen that the REF structure uses the -1 (FFFF) code to indicate deleted sheets,
     * in which case an Exception is thrown.
     */
    protected function readSheetRangeByRefIndex(int $index): string|false
    {

View on GitHub (pinned to 65b080eef4)

Solutions

1. Repair the file in Excel (Open and Repair) or round-trip it through LibreOffice, then load the result
2. Log the hex token id from the exception message and the sheet/cell context to identify the producer
3. If you control the producer, fix or avoid the nonstandard token; otherwise fall back to a values-only load

Example fix

// before
$spreadsheet = IOFactory::load('weird.xls'); // Unrecognized token 7F in formula

// after: degrade gracefully for unparseable formulas
try {
    $spreadsheet = IOFactory::load('weird.xls');
} catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) {
    $reader = new \PhpOffice\PhpSpreadsheet\Reader\Xls();
    $reader->setReadDataOnly(true);
    $spreadsheet = $reader->load('weird.xls');
}

try {
    $spreadsheet = IOFactory::load($path);
} catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) {
    if (str_contains($e->getMessage(), 'Unrecognized token')) {
        // capture the hex id from the message for diagnostics; request repaired file
    }
}

When it happens

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

Common situations: Upload endpoints accepting arbitrary .xls files; files damaged in storage or transfer; exports from unconventional tools that are 'almost BIFF8'.

Related errors

• Unrecognized space type in tAttrSpace token
• Unrecognized attribute flag in tAttr token
• Unrecognized function in formula
• Unexpected file pass record length
• Syntax error: comma expected in function $function, arg #{$n

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/b7a3ef1a5631b4d3. Report an issue: GitHub.