Table of Contents

  1. Introduction

  2. How PDF Invoicing Works in Dolibarr

  3. Key PDF Generation Engines: TCPDF vs DOMPDF

  4. Common Symptoms of PDF Display Errors

  5. Root Causes Behind PDF Invoicing Issues

  6. Step-by-Step Diagnostic Workflow

  7. Fix #1: Repairing PDF Template Errors

  8. Fix #2: Managing Font Compatibility

  9. Fix #3: Adjusting PHP Configuration for PDF Generation

  10. Fix #4: Solving File Permission and Access Issues

  11. Fix #5: Using the Right Output Method (Browser, Download, Storage)

  12. Custom Templates: Best Practices to Avoid Breakage

  13. Tips for Multi-language and RTL (Arabic, Hebrew) PDF Output

  14. Final Thoughts

1. Introduction

Dolibarr ERP & CRM is a widely adopted open-source business platform that streamlines operations ranging from invoicing and payments to stock management, CRM, accounting, and project tracking. One of its most crucial features—especially for commercial operations—is the ability to generate PDF invoices and other documents automatically.

However, many users encounter a frustrating issue: their invoices don’t display properly, don’t generate at all, or result in broken or unreadable PDFs. Whether you're self-hosted or using a cloud-based Dolibarr instance, these problems can disrupt billing workflows and damage your company’s professional image.

This guide breaks down why PDF invoices fail to render correctly in Dolibarr, how the underlying PDF generation works, and how you can diagnose and fix these issues—quickly and permanently.

2. How PDF Invoicing Works in Dolibarr

When you click “Generate PDF” in Dolibarr (for an invoice, proposal, order, etc.), the system:

  1. Uses a PHP-based template (known as a "PDF model")

  2. Fills in dynamic variables (customer name, item details, total amount, etc.)

  3. Sends this content to a PDF engine (TCPDF or DOMPDF)

  4. Outputs the result either for:

    • Immediate download

    • Browser display

    • File storage in /documents/

PDF generation is handled entirely server-side, which means the environment (PHP version, memory settings, font support) plays a critical role in success or failure.

3. Key PDF Generation Engines: TCPDF vs DOMPDF

Dolibarr supports two primary PDF rendering engines:

TCPDF (default engine in older versions)

  • Widely used in older Dolibarr releases

  • Fast and lightweight

  • Supports UTF-8 and basic image rendering

  • Poor support for CSS or advanced layouts

DOMPDF (introduced in later versions)

  • More modern and flexible

  • Supports HTML5/CSS3 layout

  • Requires more memory and heavier system resources

  • Better for custom designs and complex documents

If your invoices are blank, corrupted, or misaligned, the issue may relate to engine limitations, misconfiguration, or resource constraints.

4. Common Symptoms of PDF Display Errors

Users typically report the following problems when generating invoices:

  • Blank PDF with no content

  • Incomplete rendering (missing tables, prices, client info)

  • Misaligned text or layout shifts

  • PDF downloads but won’t open

  • Error messages like:

    • TCPDF ERROR: Some data has already been output

    • DOMPDF Fatal error: Uncaught exception

  • PDF looks correct but shows wrong language or broken characters

These symptoms indicate different root causes, ranging from server setup issues to faulty template code or missing fonts.

5. Root Causes Behind PDF Invoicing Issues

Here are the most common causes for invoice PDF failures in Dolibarr:

Cause Description
Corrupted or outdated PDF template Syntax issues or logic errors in custom PDF models
Incompatible PHP version DOMPDF and TCPDF have strict PHP requirements
Missing fonts or Unicode support Non-Latin characters break output
Low PHP memory or execution limits Large invoices fail to render due to resource exhaustion
Incorrect permissions Dolibarr can’t write to /documents/ or access templates
Output headers already sent Prevents proper file generation due to premature echo or space
Wrong file path configuration Points to non-existent or deprecated folders
Improper server encoding or locale settings Breaks multilingual PDF rendering

Each of these problems requires a different approach for resolution.

6. Step-by-Step Diagnostic Workflow

Before applying fixes, follow this structured diagnostic routine:

Step 1: Enable Developer Mode

In conf.php, enable developer mode:

php

define('DOL_DEVELOPER_MODE', 1);

This displays PDF generation debug output.

Step 2: Reproduce the Issue

  • Try different invoice models (e.g., crabe, azur, rouget)

  • Generate PDFs for small and large invoices

  • Attempt both download and preview actions

Step 3: Check Logs

  • PHP logs (/var/log/php/error.log)

  • Apache/Nginx logs (/var/log/apache2/error.log)

  • Dolibarr’s internal log file (if configured)

Step 4: Check Template Source Code

  • Go to /dolibarr/core/modules/facture/doc/

  • Review the PHP code for syntax issues, unclosed tags, or deprecated functions

7. Fix #1: Repairing PDF Template Errors

PDF models (e.g., pdf_crabe.modules.php) are written in PHP. A single misplaced character can break output.

Checklist:

  • Ensure <?php tags are not followed by spaces

  • No HTML or text output before headers are set

  • No accidental echo or print calls in logic sections

  • Variables like $this->emetteur must be properly initialized

Tip: Test with Default Templates First

Switch to Dolibarr’s default crabe model. If this works, your custom template is the issue.

8. Fix #2: Managing Font Compatibility

PDF engines require the appropriate font to display characters correctly.

Symptoms of Font Problems:

  • Arabic, Chinese, or Cyrillic text not rendering

  • Blank spaces where names or addresses should be

  • PDF displays “????” instead of letters

Solutions:

  • Switch to UTF-8 capable fonts like DejaVu Sans or FreeSerif

  • For DOMPDF, manually load fonts using load_font.php utility

  • Avoid system fonts not embedded in the PDF output

In Dolibarr, you can customize font settings per template.

9. Fix #3: Adjusting PHP Configuration for PDF Generation

DOMPDF especially requires adequate server resources.

Update php.ini:

ini

memory_limit = 512M max_execution_time = 120 upload_max_filesize = 20M post_max_size = 25M

Restart Apache/Nginx or PHP-FPM after changes.

Verify Extensions

Ensure the following PHP extensions are active:

  • mbstring

  • gd

  • dom

  • fileinfo

  • intl (for language/locale support)

Use:

bash

php -m | grep gd

10. Fix #4: Solving File Permission and Access Issues

If Dolibarr can’t write to the /documents/ folder, PDF generation silently fails.

Commands to Correct Permissions:

bash

chown -R www-data:www-data /var/www/dolibarr/documents chmod -R 755 /var/www/dolibarr/documents

Replace www-data with your web server user.

Ensure subdirectories for invoices (/documents/facture/) are present.

11. Fix #5: Using the Right Output Method (Browser, Download, Storage)

Dolibarr allows different output behaviors when generating PDF invoices:

  • Display in browser (inline)

  • Prompt for download

  • Save directly to /documents/ directory

If invoices are not rendering correctly in one method but work in another, the issue may stem from HTTP headers or browser compatibility.

Recommendations:

  • Test all output methods from the invoice page

  • Avoid sending any HTML output (like debug info) before headers

  • Check for conflicting Content-Type or Content-Disposition headers

  • Disable browser extensions that might block PDF rendering

In some cases, switching from inline display to download solves “blank screen” issues.

12. Custom Templates: Best Practices to Avoid Breakage

Creating a custom PDF model for invoices is common in Dolibarr, but it introduces potential compatibility risks with:

  • PHP version upgrades

  • PDF engine changes

  • Dolibarr core updates

To avoid future issues:

12.1 Use the Official Template Skeleton

Use an existing template (like crabe) as a starting point. Stick to Dolibarr’s internal structure:

  • Define $object correctly (usually a Facture class instance)

  • Use internal helper methods for table generation

  • Avoid hardcoded layout positions—use relative positioning

12.2 Sanitize All Output

Escape strings that may contain special characters or break encoding:

php

$this->pdf->MultiCell(..., dol_htmlentities($line->description), ...)

12.3 Validate with Developer Tools

If using custom logic (e.g., totals, discounts), validate the results against Dolibarr’s built-in PDF and on-screen display.

12.4 Keep Templates Version-Controlled

Store custom templates in Git. This allows you to:

  • Roll back broken versions

  • Track compatibility changes over time

  • Merge changes easily across Dolibarr upgrades

13. Tips for Multi-language and RTL (Arabic, Hebrew) PDF Output

Generating multilingual or right-to-left PDFs requires additional care.

13.1 Set the Correct Locale

Ensure Dolibarr is set to the user/client’s language before PDF generation:

php

$langs->setDefaultLang('ar_EG');

In some cases, you may need to force the charset:

php

header('Content-Type: application/pdf; charset=UTF-8');

13.2 Use RTL-Compatible Fonts

Fonts like Amiri, Noto Naskh Arabic, or DejaVu Sans support RTL scripts.

13.3 Enable RTL in DOMPDF

DOMPDF supports RTL only when explicitly configured:

php

$this->pdf->setRTL(true);

However, support may vary. TCPDF is generally more reliable for RTL scripts, but less flexible in design.

13.4 Avoid Mixing LTR/RTL Without Alignment Settings

In tables, always set alignment properties explicitly. Example:

php

$this->pdf->MultiCell(..., 'Client Name:', 0, 'R'); $this->pdf->MultiCell(..., $client_name, 0, 'L');

14. Final Thoughts

Generating professional PDF invoices in Dolibarr should be a seamless experience—but it can easily become a point of frustration when templates break, server settings conflict, or content fails to render.

Here’s a final checklist to ensure robust PDF output:

✅ Use official templates as a baseline for custom work
✅ Keep your PHP and Dolibarr versions aligned with module compatibility
✅ Ensure font coverage for every language you use
✅ Set correct permissions on the /documents/ directory
✅ Validate template syntax, avoid premature output
✅ Regularly test custom templates after Dolibarr upgrades
✅ If multilingual or RTL: verify font + layout behavior on real data
✅ Use logs and developer mode to trace silent errors

A small configuration oversight or outdated template can disrupt your entire invoicing workflow. But with the diagnostic framework and fixes detailed in this guide, you’ll have everything needed to troubleshoot—and prevent—PDF-related problems in Dolibarr.

By implementing these best practices, you ensure your invoice PDFs are clear, reliable, professional, and fully functional—no matter what version of Dolibarr or PHP you're using.