Troubleshooting
Installing the binary#
The plugin is blocked#
nforst/fagus contains a Composer plugin which is blocked by your allow-plugins config. You may add it to the list if you consider it safe.Composer runs without asking (in CI, in Docker builds, with --no-interaction) and
composer.json does not allow the plugin. Allow it and commit the change:
composer config allow-plugins.nforst/fagus trueIf you answered n when Composer asked, composer.json has "nforst/fagus": false; the plugin
then never runs and the engine reports that the binary was not found. Change it to true, or
install the binary with vendor/bin/fagus-install.
The binary was not found#
The fagus binary was not found. Install it with `vendor/bin/fagus-install` (in Laravel: `php artisan fagus:install`), set its path in the Engine or in the FAGUS_BINARY environment variable, or put it on the PATH.There is no binary in the package, FAGUS_BINARY is not set and there is no fagus on the
PATH. Usually the plugin did not run (--no-plugins, blocked) or could not install the binary;
composer install then printed a warning that starts with fagus:. Run the installer to see why:
vendor/bin/fagus-install
php artisan fagus:installCopying vendor/ from a machine of another platform also leaves the wrong binary behind; run the
installer on the target (deployment.md).
A binary that is given does not exist#
The fagus binary `/usr/local/bin/fagus` could not be started. It does not exist or is not executable.The path in FAGUS_BINARY, in new Engine(binary: …) or in config/fagus.php is wrong, or the
file is not executable (chmod +x). A binary that is given is never replaced by another one.
proc_open() is disabled#
The fagus binary `/app/vendor/nforst/fagus/php/fagus/bin/fagus` could not be started. PHP does not allow proc_open() (disable_functions).Remove proc_open (and proc_get_status, proc_close, proc_terminate) from
disable_functions in php.ini. Fagus runs the binary as a process and needs them.
A development version without binaries#
This version of nforst/fagus (0.0.1) is a development version without built binaries. Build the binary with `cargo build --release` and set FAGUS_BINARY to it.You installed a branch (such as dev-main) rather than a release. Only releases list the
binaries to install; the plugin installs nothing for a branch. Require a release, or build the
binary from source and set FAGUS_BINARY (deployment.md).
An unsupported platform#
There is no fagus binary for Linux on armv7l. Build it from source with `cargo build --release` and set FAGUS_BINARY to it.Releases have binaries for Linux (x64, arm64, glibc and musl), macOS (x64, arm64) and Windows (x64). Other platforms need a binary built from source.
The download failed#
The fagus binary could not be downloaded from https://github.com/nforst/fagus/releases/download/v0.1.0/fagus-x86_64-unknown-linux-gnu. The server answered 404.- From a private fork, downloads without a token fail with 404. Give Composer a token
(
composer config --global github-oauth.github.com <token>) or setFAGUS_GITHUB_TOKEN. - Without access to GitHub, point
FAGUS_DOWNLOAD_URLat a directory or URL with the files of the release (deployment.md). - With
FAGUS_DOWNLOAD_URLset to a directory, the message ends in "The file cannot be read." when the filefagus-<target>is not there.
The checksum does not match#
The downloaded fagus-x86_64-unknown-linux-gnu is not the binary of this release: its SHA-256 is 3f1c…, expected 9a07…. It was not installed.The file is not the binary of the package's release: a file of another release in
FAGUS_DOWNLOAD_URL, a proxy that changed the download, or a broken download. Nothing was
installed. Put the files of the matching release into FAGUS_DOWNLOAD_URL, or use
FAGUS_BINARY for a binary of your own.
The binary cannot be written#
The fagus binary could not be written to `/app/vendor/nforst/fagus/php/fagus/bin/fagus`. Check that the directory is writable; on Windows, also stop the processes that run the binary (queue workers, Octane), which keep it locked.The user that runs Composer cannot write into vendor/, or, on Windows, a running worker locks
the old binary.
Another protocol#
The fagus binary speaks protocol 2, this package needs protocol 1. Install the binary of the same release.FAGUS_BINARY or the PATH points to a binary of another release. Use the binary of the
package's release.
Rendering#
The worker did not answer in time#
The fagus worker did not answer within 60 seconds and was stopped.A document took longer than the engine's timeout (60 seconds by default) between two answers.
The worker was stopped; the next document starts a new one. Raise the timeout
(new Engine(timeout: 120.0), 'timeout' in config/fagus.php), render the document in a
queue, or find what makes it slow with $pdf->timings() on a smaller version of it. Windows
has no timeout.
A font directory does not exist#
The font directory `/app/resources/fonts` does not exist. Create it or remove it from the engine's font directories.A directory in the fontDirectories of new Engine(…) does not exist. The engine checks them
before it starts the worker. Create the directory (in a container image too) or leave it out.
Laravel skips the directories of its fonts configuration that do not exist, so this does not
happen there.
The worker stopped#
The fagus worker stopped. It exited with code 1. Error: reading fonts in /app/resources/fontsThe worker process ended. The message carries its exit code and the end of what it wrote to its error output. Common causes:
- A font directory cannot be read (its permissions), as in the message above.
- The process was killed from outside, for example by the kernel's out-of-memory killer. A process ended by a signal has no exit code in the message.
The engine stops the worker; the next document starts a new one. If a document makes the worker stop every time, please report it with the document.
Strict mode#
2 diagnostics in strict mode:
<style> 1:3:5: warning[css.unknown-property]: unknown property `colr`; the declaration is ignored
resources: warning[resource.not-loaded]: image `logo.png` could not be loadedstrict() turns every diagnostic into a RenderException, whose diagnostics() lists them.
Fix them, or drop strict() for documents whose diagnostics you accept.
PDF/UA requirements#
the document does not meet PDF/UA-1: the document has no title (add a <title>); the document has no language (add `lang` to <html>); the image `logo.png` in line 12 has no alternative text (add `alt`, empty if it is decoration); the first heading, an <h2> in line 14, is not an <h1> (headings start at h1)accessible() checks what PDF/UA-1 requires of the document and throws a RenderException that
lists everything missing. Its diagnostics() hold what was found before, such as an image that
could not be loaded:
| Problem | Fix |
|---|---|
| the document has no title | <title>Invoice 2026-0042</title> |
| the document has no language | <html lang="en"> |
the image … has no alternative text |
alt="…", or alt="" for decoration |
| the SVG in line … has no alternative text | a <title> or aria-label in the <svg>, or aria-hidden="true" for decoration |
| the formula in line … has no alternative text | alttext on <math> |
the first heading … is not an <h1> |
start with <h1> |
the <h3> in line … follows an <h1> |
headings skip no level: use an <h2> |
PDF/A requirements#
the document does not meet PDF/A-2b: PDF/A-2 allows only PDF/A files as attachments; attach `timesheet.csv` to a PDF/A-3 document insteadThe PDF cannot meet the PDF/A level that was asked for. PDF/A-2 allows only PDF/A files as
attachments; use PDF/A-3 (pdfA('3b')) for other files. See pdf.md. The exception's
diagnostics() hold what was found before the PDF was refused.
An unknown PDF/A level#
Unknown PDF/A level '4z'. The levels are '2b', '2u', '2a', '3b', '3u', '3a'.pdfA() got a string that is not a level. It throws a Fagus\Exception\InvalidArgumentException
when it is called, before anything is rendered. Pass one of the levels, or a Conformance case.
The PDF cannot be saved#
The PDF could not be written to `/var/www/storage/invoices/2026-0042.pdf`.The directory does not exist or is not writable. save() does not create directories.
An internal error#
internal error while rendering: …Fagus stopped where it should not. This is a bug; please report it with the document.
Read diagnostics#
Every Pdf carries the diagnostics of its document: what Fagus ignored or could not load, with
the position in the source.
$pdf = Fagus::html($html)->baseDirectory(__DIR__.'/assets')->render();
foreach ($pdf->diagnostics() as $diagnostic) {
echo $diagnostic, "\n";
}html:4: warning[resource.not-loaded]: stylesheet `css/missing.css` could not be loaded
<style> 1:1:34: warning[css.unknown-property]: unknown property `colr`; the declaration is ignored
resources: warning[resource.not-loaded]: image `https://example.com/a.png` could not be loadedEach line reads source:line:column: severity[code]: message. The source is <style> 1 for the
first <style> element, the URL of a linked or imported stylesheet, the name given to
stylesheet(), html for the markup, resources for loaded files and pdf for the output.
| Code | Meaning |
|---|---|
css.unknown-property |
A property Fagus does not know; the declaration is ignored. |
css.invalid-value |
A value the property does not take; the declaration is ignored. |
css.parse-error |
A rule or declaration that cannot be parsed; it is ignored. |
css.unparsable |
Rules or declarations the CSS parser cannot handle are left out. |
css.too-deep |
Blocks or functions nest too deep; the stylesheet is ignored. |
html.too-deep |
Elements nest hundreds of levels deep; the rest of the document is left out (severity error). |
resource.not-loaded |
A stylesheet, image, font or SVG reference could not be loaded (resources.md). |
image.unsupported |
An image is not PNG, JPEG, GIF, WebP or SVG, or not a valid SVG. |
image.too-large |
An image has more than 200 megapixels. |
image.broken |
An image could not be decoded and is left out. |
font.unsupported |
A file is not a font Fagus can read, or an installed font has no glyphs it can draw. |
font.missing-glyph |
No font has a glyph for some characters; they are drawn as empty boxes (fonts.md). |
frame.limit |
The documents in frames reach their limit; later frames show nothing. |
layout.too-many-pages |
The document reaches the limit of 10,000 pages; what follows is left out. |
pdf.conformance-raised |
Factur-X needs PDF/A-3; a PDF/A-2 level was raised to the PDF/A-3 level of the same letter. |
invoice.profile-mismatch |
The invoice XML declares another profile than the one given. |
invoice.profile-unknown |
The invoice XML declares no Factur-X profile. |
Declarations in style attributes are not reported. Diagnostics of documents in frames are not
reported either.
It looks different from Chrome#
Fagus aims to print like Chrome on Linux. When a PDF differs from Chrome's, check these first.
- Fonts. Chrome uses the fonts installed on the machine; Fagus does not by default, so that
every machine prints the same. A family Fagus does not have falls back, in the end to the
built-in Inter. Load the fonts with
@font-face, put them in a font directory, or turn onsystemFonts(fonts.md). Look forresource.not-loadeddiagnostics of fonts. - Paper size. Without
@page { size }, Fagus prints A4; Chrome uses the paper size of its print settings, which is Letter in the United States. Set the size in the document:@page { size: A4 }or@page { size: letter }. - Margins. Chrome's print dialog has its own margin settings. Set
@page { margin: … }in the document and choose "Default" margins in Chrome to compare. - Print media. Fagus applies
@media printrules and never@media screenones, as Chrome does when it prints. A page that looks right in the browser window can differ in print: compare with Chrome's print preview, not with the window. Tailwind'sprint:variants apply. - Width of the page. Media queries and viewport units see the page area, not a browser
window: A4 with Fagus's default margins is about 720 px wide, below Tailwind's
mdbreakpoint (768 px). In Chrome's print preview, the page area is below it too. - Backgrounds. Fagus prints backgrounds and shadows. Turn on "Background graphics" in Chrome's print dialog to compare.
- Headers and footers. Chrome adds the date, title and URL in its own headers and footers;
turn them off in the print dialog. Fagus prints only the margin boxes of
@page. - Scripts. Fagus runs no JavaScript. Content that scripts create in the browser (charts, client-side templates) is missing; render it on the server.
- Remote resources. Images, fonts and stylesheets with
https://URLs are not loaded (resources.md). - Form controls. Fagus writes the texts of form controls (button labels, date formats) in
the language of the control's
lang, else the engine'slocale; Chrome writes them in the language of its user interface.
css.md lists where Fagus deliberately differs from Chrome, and paged-media.md describes pages, margins and headers.
FAQ#
How do I add page numbers, headers and footers?#
With @page margin boxes in the document. A running element repeats an element of the
document in a margin box:
@page {
@top-left { content: element(letterhead); }
@bottom-right { content: "Page " counter(page) " of " counter(pages); }
}
.letterhead { position: running(letterhead); }See paged-media.md.
How do I force a page break?#
.page-break { break-before: page; }Can I fetch images from a URL?#
Not through Fagus. Hand them over with resource(), or answer the URLs with a resolver() that
fetches what you allow (resources.md).
Can Fagus render a page of my running site?#
No. Fagus renders HTML that you give it. Render the view on the server (in Laravel,
Fagus::view()), and make its files available through the base directory.
Migrating from Dompdf#
Dompdf supports CSS 2.1 with some additions, without flex or grid. With Fagus, layouts with flex,
grid, calc() and custom properties work as in Chrome, so the table-based workarounds can go.
| Dompdf | Fagus |
|---|---|
$dompdf->loadHtml($html); $dompdf->render(); $dompdf->output() |
Fagus::html($html)->render()->bytes() |
$dompdf->setPaper('A4', 'landscape') |
@page { size: A4 landscape } |
$dompdf->stream('invoice.pdf') |
Fagus::html($html)->name('invoice.pdf')->inline() (Laravel), or send bytes() |
chroot |
baseDirectory() and root() |
isRemoteEnabled |
not available; resource() or resolver() |
<script type="text/php"> for page numbers |
counter(page) and counter(pages) in @page margin boxes |
isPhpEnabled, isJavascriptEnabled |
not available |
barryvdh/laravel-dompdf: Pdf::loadView('invoice', $data)->download('invoice.pdf') |
Fagus::view('invoice', $data)->download('invoice.pdf') |
->stream() |
->inline(), or return the PendingPdf |
->save($path) |
->save($path), or ->store($path, $disk) |
Fonts that Dompdf loaded from @font-face load the same way; fonts registered in its font
cache go into a font directory.
Migrating from mPDF#
mPDF has its own HTML and CSS support, with page features written as custom tags and placeholders. Fagus uses standard CSS for them.
| mPDF | Fagus |
|---|---|
new Mpdf(['format' => 'A4', 'margin_left' => 20, …]) |
@page { size: A4; margin: 20mm } |
$mpdf->WriteHTML($html); $mpdf->Output('invoice.pdf', 'F') |
Fagus::html($html)->save('invoice.pdf') |
$mpdf->Output('', 'S') |
Fagus::html($html)->render()->bytes() |
SetHTMLHeader(), SetHTMLFooter(), <htmlpageheader> |
@page margin boxes with running elements |
{PAGENO}, {nbpg} |
counter(page), counter(pages) |
<pagebreak> |
break-before: page |
PDFA, PDFAauto |
pdfA('3b') |
SetAssociatedFiles() |
attach() or facturX() |
fontDir, fontdata |
@font-face, or fontDirectories on the engine |
SetTitle(), SetAuthor() |
<title>, <meta name="author"> |
SetWatermarkText() |
a positioned element or a background in the document |
Migrating from Browsershot, Snappy or other browser-based tools#
Browsershot (and spatie/laravel-pdf on top of it) runs Chrome through Puppeteer and Node; Snappy runs wkhtmltopdf, an old WebKit. Fagus needs neither. HTML and CSS that print well in Chrome print the same in Fagus; what changes is everything around them:
| Browsershot / laravel-pdf / Snappy | Fagus |
|---|---|
Browsershot::html($html)->format('A4')->margins(…)->save('x.pdf') |
@page { size: A4; margin: … } and Fagus::html($html)->save('x.pdf') |
Pdf::view('invoice', $data)->format('a4')->name('invoice.pdf') |
Fagus::view('invoice', $data)->name('invoice.pdf') |
->showBackground() |
not needed: backgrounds always print |
->headerHtml(), ->footerHtml(), --header-html with pageNumber and totalPages |
@page margin boxes with counter(page) and counter(pages) |
->emulateMedia('screen') |
not available: Fagus applies print styles; move rules out of @media screen |
->waitUntilNetworkIdle(), ->setDelay(), JavaScript |
not available: no network, no scripts |
Browsershot::url('https://…'), $snappy->generate($url, …) |
render the HTML yourself and pass it to Fagus::html() |
$snappy->getOutputFromHtml($html) |
Fagus::html($html)->render()->bytes() |
| Assets loaded from the running site | files through baseDirectory(), or resource() and resolver() |
Remove Chrome, Node, Puppeteer or wkhtmltopdf from the servers once nothing else needs them.