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

Unrecognized function in formula

Error message

Unrecognized function in formula

What it means

A tFunc token references a built-in sheet function by 2-byte index, and that index has no entry in the reader's TFUNC_MAPPINGS table. The file uses a function slot PhpSpreadsheet's mapping table does not know, so it cannot render the formula.

Source

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

                break;
            case 0x20:    //    array constant
            case 0x40:
            case 0x60:
                // offset: 1; size: 7; not used
                $name = 'tArray';
                $size = 8;
                $data = null;

                break;
            case 0x21:    //    function with fixed number of arguments
            case 0x41:
            case 0x61:
                $name = 'tFunc';
                $size = 3;
                // offset: 1; size: 2; index to built-in sheet function
                $mapping = Xls\Mappings::TFUNC_MAPPINGS[self::getUInt2d($formulaData, 1)] ?? null;
                if ($mapping === null) {
                    throw new Exception('Unrecognized function in formula');
                }
                $data = ['function' => $mapping[0], 'args' => $mapping[1]];

                break;
            case 0x22:    //    function with variable number of arguments
            case 0x42:
            case 0x62:
                $name = 'tFuncV';
                $size = 4;
                // offset: 1; size: 1; number of arguments
                $args = ord($formulaData[1]);
                // offset: 2: size: 2; index to built-in sheet function
                $index = self::getUInt2d($formulaData, 2);
                $function = Xls\Mappings::TFUNCV_MAPPINGS[$index] ?? null;
                if ($function === null) {
                    throw new Exception('Unrecognized function in formula');
                }
                $data = ['function' => $function, 'args' => $args];

View on GitHub (pinned to 65b080eef4)

Solutions

1. Upgrade PhpSpreadsheet — function maps gain entries over releases
2. Open the file in Excel, replace the newer function with a classic equivalent (e.g. replace XLOOKUP with INDEX/MATCH), and re-save
3. Re-save as .xlsx and use the Xlsx reader, whose function handling is broader
4. If unreachable, strip the formulas (paste-values) before import

Example fix

// before
$spreadsheet = IOFactory::load('newfuncs.xls'); // Unrecognized function in formula

// after: convert to xlsx, whose reader handles newer functions
shell_exec('soffice --headless --convert-to xlsx --outdir /tmp newfuncs.xls');
$spreadsheet = IOFactory::load('/tmp/newfuncs.xlsx');

try {
    $spreadsheet = IOFactory::load($path);
} catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) {
    if (str_contains($e->getMessage(), 'Unrecognized function')) {
        $reader = new \PhpOffice\PhpSpreadsheet\Reader\Xls();
        $reader->setReadDataOnly(true);
        $spreadsheet = $reader->load($path); // values-only fallback
    }
}

When it happens

Trigger: Loading an .xls saved by a newer Excel that occupied previously-reserved function indexes, or a writer that emitted a wrong index; corrupt bytes in the token produce the same effect.

Common situations: Workbooks authored in a later Office version than the library's mapping table covers; spreadsheets generated by third-party toolkits with hand-rolled BIFF output.

Related errors

• Unrecognized space type in tAttrSpace token
• Unrecognized attribute flag in tAttr token
• Unrecognized token %02X 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/680fba406ea04ef7. Report an issue: GitHub.