Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

mPDF prints a broken image icon instead of the picture

Errorimage displays as a broken [x]

Short answer

mPDF draws a placeholder when it cannot load an image. Turn on showImageErrors first: it reports why. The usual causes are a relative path resolved against the wrong place, spaces in the file name, or a format mPDF does not support in your version. Set a base path, encode the name, or convert the file.

  • Applies to mPDF 8, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Switch on image error reporting before WriteHTML. mPDF then tells you which image failed instead of drawing a placeholder.

    $mpdf = new \Mpdf\Mpdf();
    $mpdf->showImageErrors = true;
    $mpdf->WriteHTML($html);
    $mpdf->Output();
  2. 2Match what you see, then jump to its fix

    1. 1The image works in the browser but not in the PDF, and the src is something like ../images/logo.pngA relative path is resolved against the wrong placeFix
    2. 2Only images whose names have spaces failThe file name contains spacesFix
    3. 3The failing file is WEBP, or a format outside GIF, PNG, JPG, WMF, SVG and BMPThe image format is not supported by this mPDF versionFix

What does the error look like?

  • image displays as a broken [x]
  • placeholder icon in place of the image in the PDF

Cause 1 of 3

A relative path is resolved against the wrong place

1Check

mPDF resolves relative URLs against the current script unless you set a base path. This matters for hyperlinks, stylesheets and images.

grep -n 'src=' invoice.html | head

2Fix

Tell mPDF where relative URLs start. Give a full URL as the base, as the reference documents it.

$mpdf = new \Mpdf\Mpdf();
$mpdf->SetBasePath('https://www.example.com/app/');
$mpdf->WriteHTML('<img src="images/logo.png" width="40mm">');

3Verify

Generate the PDF again. The picture replaces the placeholder.

php make-pdf.php

Confirmed by mpdf.github.io

Did this fix it?

Cause 2 of 3

The file name contains spaces

1Check

mPDF's troubleshooting page says image files containing spaces may cause problems.

ls -1 images | grep ' '

2Fix

Rename the file without spaces, or replace each space with %20 in the src, for example with urlencode on the name.

$file = 'company logo.png';
$src  = 'images/' . str_replace(' ', '%20', $file);
$html = '<img src="' . $src . '">';

3Verify

Run the script again and open the PDF.

php make-pdf.php

Confirmed by mpdf.github.io

Did this fix it?

Cause 3 of 3

The image format is not supported by this mPDF version

1Check

mPDF lists GIF, PNG, JPG, WMF, SVG, BMP and WEBP, and WEBP support starts in v8.0.16. Check the installed version and the real format of the file.

composer show mpdf/mpdf | head -5
file images/photo.webp

2Fix

Upgrade mPDF to a release that supports WEBP, or convert the picture to PNG or JPG before you pass it in. JPG is the fastest to process.

composer update mpdf/mpdf

3Verify

Generate the PDF again. The converted or upgraded image should render.

php make-pdf.php

Confirmed by mpdf.github.io

Did this fix it?

How do I stop it coming back?

  • Keep showImageErrors = true in development and in test runs.
  • Use names without spaces for every file that is rendered into a PDF.
  • Set the base path once, right after you create the Mpdf object.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.