Skip to content
You are reading the documentation of the unreleased development version.Go to the latest release

Troubleshooting

Installing the binary#

The plugin is blocked#

text
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:

sh
composer config allow-plugins.nforst/fagus true

If 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#

text
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:

sh
vendor/bin/fagus-install
php artisan fagus:install

Copying 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#

text
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#

text
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#

text
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#

text
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#

text
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 set FAGUS_GITHUB_TOKEN.
  • Without access to GitHub, point FAGUS_DOWNLOAD_URL at a directory or URL with the files of the release (deployment.md).
  • With FAGUS_DOWNLOAD_URL set to a directory, the message ends in "The file cannot be read." when the file fagus-<target> is not there.

The checksum does not match#

text
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#

text
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#

text
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#

text
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#

text
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#

text
The fagus worker stopped. It exited with code 1. Error: reading fonts in /app/resources/fonts

The 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#

text
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 loaded

strict() turns every diagnostic into a RenderException, whose diagnostics() lists them. Fix them, or drop strict() for documents whose diagnostics you accept.

PDF/UA requirements#

text
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#

text
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 instead

The 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#

text
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#

text
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#

text
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.

php
$pdf = Fagus::html($html)->baseDirectory(__DIR__.'/assets')->render();

foreach ($pdf->diagnostics() as $diagnostic) {
    echo $diagnostic, "\n";
}
text
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 loaded

Each 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 on systemFonts (fonts.md). Look for resource.not-loaded diagnostics 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 print rules and never @media screen ones, 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's print: 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 md breakpoint (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's locale; 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:

css
@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?#

css
.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.