PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

TrueType Font file not found

Error message

TrueType Font file not found

What it means

Thrown by Font::getTrueTypeFontFileFromFont() after it failed to locate the .ttf file for the requested style. When the primary mapped filename is not on disk, the code builds an 'alternate name' (font name plus ' Bold'/' Italic'/' Bold Italic') inside the configured font directory; if that file also does not exist, this exception is raised.

Source

Thrown at src/PhpSpreadsheet/Shared/Font.php:597

                // Neither bold nor italic:
                //   Impact
                //   Lucida Console
                //   Lucida Sans Unicode
                //   Microsoft Sans Serif
                //   Symbol
                if ($index === 'xb') {
                    $alternateName .= ' Bold';
                } elseif ($index === 'xi') {
                    $alternateName .= ' Italic';
                } elseif ($fontArray[$name]['xb'] === $fontArray[$name]['xbi']) {
                    $alternateName .= ' Bold';
                } else {
                    $alternateName .= ' Bold Italic';
                }
            }
            $fontFile = self::$trueTypeFontPath . $separator . $alternateName . '.ttf';
            if (!file_exists($fontFile)) {
                throw new PhpSpreadsheetException('TrueType Font file not found');
            }
        }

        return $fontFile;
    }

    public const CHARSET_FROM_FONT_NAME = [
        'EucrosiaUPC' => self::CHARSET_ANSI_THAI,
        'Wingdings' => self::CHARSET_SYMBOL,
        'Wingdings 2' => self::CHARSET_SYMBOL,
        'Wingdings 3' => self::CHARSET_SYMBOL,
    ];

    /**
     * Returns the associated charset for the font name.
     *
     * @param string $fontName Font name
     *

View on GitHub (pinned to 65b080eef4)

Solutions

1. List Font::getTrueTypeFontPath() and confirm every variant used by the sheet (regular, bold, italic, bold-italic) exists with the exact filename (case-sensitive on Linux).
2. When registering custom fonts via Font::setExtraFontArray(), provide all four keys ('x','xb','xi','xbi') with the real filenames from the directory.
3. Rename the files on disk to match the alternate-name convention the fallback expects ('<Font Name> Bold.ttf', '<Font Name> Italic.ttf', '<Font Name> Bold Italic.ttf').
4. Alternatively drop to Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_APPROX) so no font file is opened at all.

Example fix

// before
// /var/www/fonts contains only calibri.ttf, sheet uses bold font
Font::setTrueTypeFontPath('/var/www/fonts');
Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_EXACT);
// TrueType Font file not found

// after
// copy all variants into the directory:
// calibri.ttf calibrib.ttf calibrii.ttf calibriz.ttf
Font::setTrueTypeFontPath('/var/www/fonts');
Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_EXACT);

$dir = \PhpOffice\PhpSpreadsheet\Shared\Font::getTrueTypeFontPath();
foreach (['', ' Bold', ' Italic', ' Bold Italic'] as $suffix) {
    $file = "$dir/{$fontName}{$suffix}.ttf";
    if (!is_file($file)) { /* ensure the file is deployed before enabling exact autosize */ }
}

try { $writer->save($path); }
catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    if (str_contains($e->getMessage(), 'TrueType Font file not found')) {
        \PhpOffice\PhpSpreadsheet\Shared\Font::setAutoSizeMethod(Font::AUTOSIZE_METHOD_APPROX);
        $writer->save($path);
    } else { throw $e; }
}

When it happens

Trigger: Font::setTrueTypeFontPath($dir) points to a directory that lacks the specific style variant, e.g. cells formatted bold with Calibri while only calibri.ttf (no calibrib.ttf) is in the directory; or an extra-font array whose filenames do not match what is actually on disk; or the extra array omitted the 'xb'/'xi'/'xbi' keys so the alternate-name fallback runs and its file is missing.

Common situations: Copying only the regular weight of a font into the container; case-sensitivity surprises on Linux when the file is Calibri.TTF but the code looks for calibri.ttf; an extra font array written with placeholder filenames never replaced; fonts directory mounted read-only and incompletely populated.

Related errors

• imagettfbbox failed
• Valid directory to TrueType Font files not specified
• Unknown font name "$name". Cannot map to TrueType font file
• Can't open file $filename
• File $path not found!

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