{"record":{"id":"27afe138237413dd","repo":"PHPOffice/PhpSpreadsheet","slug":"unknown-font-name-name-cannot-map-to-truetype","errorCode":null,"errorMessage":"Unknown font name \"$name\". Cannot map to TrueType font file","messagePattern":"Unknown font name \"\\$name\"\\. Cannot map to TrueType font file","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Shared/Font.php","lineNumber":550,"sourceCode":"    {\n        return $sizeInCm * 37.795275591;\n    }\n\n    /**\n     * Returns the font path given the font.\n     *\n     * @return string Path to TrueType font file\n     */\n    public static function getTrueTypeFontFileFromFont(FontStyle $font, bool $checkPath = true): string\n    {\n        if ($checkPath && (!file_exists(self::$trueTypeFontPath) || !is_dir(self::$trueTypeFontPath))) {\n            throw new PhpSpreadsheetException('Valid directory to TrueType Font files not specified');\n        }\n\n        $name = $font->getName();\n        $fontArray = array_merge(self::FONT_FILE_NAMES, self::$extraFontArray);\n        if (!isset($fontArray[$name])) {\n            throw new PhpSpreadsheetException('Unknown font name \"' . $name . '\". Cannot map to TrueType font file');\n        }\n        $bold = $font->getBold();\n        $italic = $font->getItalic();\n        $index = 'x';\n        if ($bold) {\n            $index .= 'b';\n        }\n        if ($italic) {\n            $index .= 'i';\n        }\n        $fontFile = $fontArray[$name][$index];\n\n        $separator = '';\n        if (mb_strlen(self::$trueTypeFontPath) > 1 && mb_substr(self::$trueTypeFontPath, -1) !== '/' && mb_substr(self::$trueTypeFontPath, -1) !== '\\\\') {\n            $separator = DIRECTORY_SEPARATOR;\n        }\n        $fontFileAbsolute = preg_match('~^([A-Za-z]:)?[/\\\\\\]~', $fontFile) === 1;\n        if (!$fontFileAbsolute) {","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Shared/Font.php#L532-L568","documentation":"Thrown by Font::getTrueTypeFontFileFromFont() when the font's name does not appear in the built-in FONT_FILE_NAMES map nor in the extra array registered via Font::setExtraFontArray(). The library can only compute exact text widths for fonts it can map to a .ttf file, so an unregistered name is fatal for the 'exact' auto-size path.","triggerScenarios":"Setting a cell/row/default font name that is not one of the known mappings (e.g. $sheet->getStyle('A1')->getFont()->setName('Roboto')) and then saving with Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_EXACT); the lookup `array_merge(self::FONT_FILE_NAMES, self::$extraFontArray)` finds no key 'Roboto' and throws. Also triggered by name case/whitespace mismatches, since the lookup is an exact isset() on the string.","commonSituations":"Corporate-brand fonts (Roboto, Lato, Source Sans) applied to generated reports; copying a font name with a trailing space or wrong casing from a design spec; a file loaded from a template whose theme font is unusual, then re-saved with exact auto-size enabled.","solutions":["Register the font before saving: Font::setExtraFontArray(['Roboto' => ['xb' => 'Roboto-Regular.ttf', 'xbi' => 'Roboto-BoldItalic.ttf', 'xi' => 'Roboto-Italic.ttf', 'x' => 'Roboto-Bold.ttf']]) in the documented shape, with the files present in Font::getTrueTypeFontPath().","Prefer one of the well-known mapped names (Calibri, Arial, Times New Roman, Courier New, ...) for the fonts used in auto-sized columns.","Normalize the name you set (trim, exact casing) and check membership before saving: in_array($name, array_keys(array_merge(Font::FONT_FILE_NAMES, Font::getExtraFontArray())), true).","If exact mapping is impossible, fall back to Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_APPROX)."],"exampleFix":"// before\n$sheet->getStyle('A1')->getFont()->setName('Roboto');\nFont::setAutoSizeMethod(Font::AUTOSIZE_METHOD_EXACT);\n$writer->save('out.xlsx'); // Unknown font name \"Roboto\"\n\n// after\nFont::setTrueTypeFontPath('/var/www/fonts');\nFont::setExtraFontArray(['Roboto' => [\n    'x' => 'Roboto-Regular.ttf', 'xb' => 'Roboto-Bold.ttf',\n    'xi' => 'Roboto-Italic.ttf', 'xbi' => 'Roboto-BoldItalic.ttf',\n]]);\n$sheet->getStyle('A1')->getFont()->setName('Roboto');","handlingStrategy":"validation","validationCode":"use PhpOffice\\PhpSpreadsheet\\Shared\\Font;\nfunction fontIsMeasurable(string $name): bool\n{\n    $known = array_merge(Font::FONT_FILE_NAMES, Font::getExtraFontArray());\n    return isset($known[trim($name)]);\n}\n// before save:\nforeach ($sheet->getStyleCollection?? [] as $_) {} // (iterate your styles as needed)\nif (!fontIsMeasurable($fontName)) { /* register extra array or switch font */ }","typeGuard":"function measurableFontName(string $name): ?string\n{\n    $known = array_merge(Font::FONT_FILE_NAMES, Font::getExtraFontArray());\n    return isset($known[$name]) ? $name : null; // narrow to a usable name\n}","tryCatchPattern":"try { $writer->save($path); }\ncatch (\\PhpOffice\\PhpSpreadsheet\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Unknown font name')) {\n        // register the font or fall back to approx sizing, then retry\n        Font::setExtraFontArray(array_merge(Font::getExtraFontArray(), $extraDefs));\n        $writer->save($path);\n    } else { throw $e; }\n}","preventionTips":["Centralize font selection: limit cells to names present in Font::FONT_FILE_NAMES or your registered extra array.","Register custom fonts via Font::setExtraFontArray() in the same bootstrap that sets the font path, so name and file are configured together."],"tags":["fonts","configuration","column-autosize","phpspreadsheet"],"backgroundTag":"unregistered-font-name","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}