{"record":{"id":"ad198968ea70c008","repo":"PHPOffice/PhpSpreadsheet","slug":"code-page-codepage-not-implemented-on-this-system","errorCode":null,"errorMessage":"Code page $codePage not implemented on this system.","messagePattern":"Code page \\$codePage not implemented on this system\\.","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Shared/CodePage.php","lineNumber":98,"sourceCode":"     *\n     * @param int $codePage Microsoft Code Page Identifier\n     *\n     * @return string Code Page Name\n     */\n    public static function numberToName(int $codePage): string\n    {\n        if (array_key_exists($codePage, self::$pageArray)) {\n            $value = self::$pageArray[$codePage];\n            if (is_array($value)) {\n                foreach ($value as $encoding) {\n                    if (@iconv('UTF-8', $encoding, ' ') !== false) {\n                        self::$pageArray[$codePage] = $encoding;\n\n                        return $encoding;\n                    }\n                }\n\n                throw new PhpSpreadsheetException(\"Code page $codePage not implemented on this system.\");\n            } else {\n                return $value;\n            }\n        }\n        if ($codePage == 720 || $codePage == 32769) {\n            throw new PhpSpreadsheetException(\"Code page $codePage not supported.\"); //    OEM Arabic\n        }\n\n        throw new PhpSpreadsheetException('Unknown codepage: ' . $codePage);\n    }\n\n    /** @return array<int, array<int, string>|string> */\n    public static function getEncodings(): array\n    {\n        return self::$pageArray;\n    }\n}\n","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Shared/CodePage.php#L80-L116","documentation":"Shared\\CodePage::numberToName() maps BIFF code-page IDs (read from .xls CODEPAGE records) to iconv encodings; some IDs map to a list of candidate encodings probed with iconv at runtime. This variant means the code page IS known, but every candidate encoding is unavailable in the system's iconv build, so cell text in the workbook cannot be decoded.","triggerScenarios":"Reading a legacy .xls whose code page resolves only to encodings compiled out of the runtime iconv (e.g. IBM/EBCDIC pages on minimal builds); reading such a file inside an Alpine/musl-based container where iconv supports only a small encoding set.","commonSituations":"Docker Alpine images (musl iconv lacks many encodings); PHP built against a minimal libiconv; archived workbooks from mainframe-era or non-Windows locales.","solutions":["Run the reader in a glibc-based image (Deity/debian-based) or otherwise provide a full iconv build","Convert the workbook before processing: libreoffice --headless --convert-to xlsx file.xls","If you control generation, save the .xls with a Unicode code page (UTF-16/UTF-8)","Verify the runtime: iconv -l | grep -i <encoding> to confirm which encodings exist"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight: confirm the runtime iconv supports the encodings your files need\nforeach (['IBM437', 'CP850', 'WINDOWS-1252'] as $enc) {\n    if (@iconv('UTF-8', $enc, ' ') === false) {\n        throw new RuntimeException(\"iconv build lacks $enc; use a glibc image\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    $spreadsheet = (new \\PhpOffice\\PhpSpreadsheet\\Reader\\Xls())->load($path);\n} catch (\\PhpOffice\\PhpSpreadsheet\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Code page')) {\n        // re-encode the file externally (LibreOffice) and retry once\n    }\n}","preventionTips":["Prefer glibc-based runtime images over Alpine for legacy .xls processing","Convert legacy workbooks to .xlsx at ingest time","Probe iconv availability in smoke tests before deployment"],"tags":["xls","encoding","iconv","environment","legacy"],"backgroundTag":"unsupported-encoding","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}