Intervention/image · error · DriverException

Unable to calculate box size of font

Error message

Unable to calculate box size of font

What it means

The GD FontProcessor measures text by calling imageftbbox(); it returns false when FreeType cannot work with the given font file or text. The usual cause is a missing, unreadable, or invalid font path rather than anything about the image being annotated.

Source

Thrown at src/Drivers/Gd/FontProcessor.php:56

                    $chars * $this->gdCharacterWidth($gdFont),
                );
                $box->setHeight(
                    $this->gdCharacterHeight($gdFont),
                );
            }
            return $box;
        }

        // calculate box size from ttf font file with angle 0
        $box = imageftbbox(
            size: $this->nativeFontSize($font),
            angle: 0,
            font_filename: $font->filepath(),
            string: $text,
        );

        if ($box === false) {
            throw new DriverException('Unable to calculate box size of font');
        }

        // build size from points
        return new Size(
            width: intval(abs($box[6] - $box[4])), // difference of upper-left-x and upper-right-x
            height: intval(abs($box[7] - $box[1])), // difference if upper-left-y and lower-left-y
            pivot: new Point($box[6], $box[7]), // position of upper-left corner
        );
    }

    /**
     * {@inheritdoc}
     *
     * @see FontProcessorInterface::nativeFontSize()
     */
    public function nativeFontSize(FontInterface $font): float
    {
        return floatval(round($font->size() * .76, 6));

View on GitHub (pinned to 5598b9e397)

Solutions

1. Verify with file_exists() and is_readable() before rendering
2. Use absolute paths built from __DIR__ or a configured asset root
3. Confirm the file is TTF/OTF, not WOFF/WOFF2; convert if needed
4. Sanity-test the font with imageftbbox(12, 0, $font, 'Test') directly
5. Use the Imagick driver's text rendering as a fallback for exotic fonts

Example fix

// before
$image->text('Hello', 100, 100, 'app/fonts/missing.ttf');

// after
$fontFile = realpath(__DIR__ . '/../fonts/inter.ttf');
if ($fontFile === false || !is_readable($fontFile)) {
    throw new RuntimeException('Font file missing or unreadable');
}
$image->text('Hello', 100, 100, $fontFile);

if (!is_string($fontFile) || !is_readable($fontFile)) {
    throw new RuntimeException('Font file not readable: ' . $fontFile);
}
$image->text('Hello', 100, 100, $fontFile);

function isReadableFont(mixed $font): bool
{
    return is_string($font) && is_readable($font);
}

try {
    $image->text('Hello', 100, 100, $fontFile);
} catch (DriverException $e) {
    // font unreadable/invalid: fall back to a bundled default font
}

When it happens

Trigger: $image->text('Hi', 100, 100, 'fonts/missing.ttf') where the path is wrong or unreadable; a font format FreeType cannot parse (e.g. WOFF); relative paths resolving differently between CLI and web SAPIs.

Common situations: Font path typos, font assets not copied into Docker builds, file permissions on shared hosting, passing .woff files that must be converted to TTF first.

Related errors

• Failed to apply ' . self::class . ', unable to draw text lin
• Unable to parse RGB color from input "{input}"
• Color channel {classname} could not be found
• Unknown color space ({colorspace}) as conversion target
• Class '{objectShortname}' is not supported by {id} driver

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/a3698b54033bd70b. Report an issue: GitHub.