Fix Odoo PDF Reports With Blank or Missing Headers and Footers

The Problem

You click "Print" on an invoice or sales order and the PDF either has no header/footer, shows a blank first page, cuts off content, or fails entirely with a 500 Internal Server Error. PDF report issues are among the most common Odoo support tickets.

Error Messages You Might See

# In Odoo logs:
wkhtmltopdf: error while loading shared libraries: libXrender.so.1
OSError: wkhtmltopdf exited with non-zero code -6
QWebException: 'NoneType' object has no attribute 'company_id'
ValueError: External ID not found in the system: web.external_layout

Common Causes and Fixes

1. wkhtmltopdf Not Installed or Wrong Version

Odoo uses wkhtmltopdf to convert HTML reports to PDF. The version matters enormously — Odoo requires a specific patched version with Qt patches for headers and footers.

Fix:

# Check current version
wkhtmltopdf --version

# Required: 0.12.6.1 (with patched Qt)
# Download the correct version for your OS:
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
sudo apt-get install -f  # fix any missing dependencies

Using the wrong version (especially from apt repositories) gives you an unpatched build that cannot render headers and footers.

2. Missing System Libraries

wkhtmltopdf needs X11 libraries even in headless mode:

# Install required libraries
sudo apt-get install -y libxrender1 libfontconfig1 libx11-6 \
  libxext6 libfreetype6 libjpeg-turbo8 xfonts-75dpi xfonts-base

3. Company Not Set on Document

The external layout template accesses docs.company_id. If the record has no company set, the header crashes.

Error:

QWebException: 'NoneType' object has no attribute 'logo'
Template: web.external_layout_standard

Fix: Ensure the document (invoice, SO, etc.) has a company set. Check Settings > Companies to make sure your company has a logo uploaded.

4. Custom Header Template Errors

If you customized the report header/footer template and introduced an error, it breaks all reports.

Debug approach:

# Temporarily switch to default layout:
# Settings > General Settings > Document Layout > select "Standard"

# If reports work with Standard layout, the bug is in your custom template.
# Check your custom external layout QWeb template for:
# - Missing t-if guards for optional fields
# - Hardcoded record IDs that don't exist
# - Broken image references

5. Blank First Page

A classic wkhtmltopdf issue where the header is so tall it pushes all content to page 2, leaving page 1 blank.

Fix: Reduce header height via CSS or the company document layout settings:

<style>
  .header-section {
    max-height: 80px;
    overflow: hidden;
  }
  /* Or reduce the top margin in the report paperformat */
</style>

Or adjust the paper format: Settings > Technical > Report Paper Format. Reduce the top margin value.

6. Paper Format Margin Issues

wkhtmltopdf uses separate margin settings for the main content area and the header/footer regions. If these overlap, content gets cut off or hidden.

Fix: Go to Settings > Technical > Reporting > Paper Format. The key fields:

• Top Margin: must be greater than header height
• Bottom Margin: must be greater than footer height
• Header Spacing: gap between header and content (usually 35-45mm)

7. Docker/Container Issues

In Docker environments, wkhtmltopdf often fails because X11 libraries or fonts are missing from the container image.

Fix for Docker:

# Add to your Dockerfile:
RUN apt-get update && apt-get install -y --no-install-recommends \
    wkhtmltopdf \
    fonts-dejavu-core \
    fonts-freefont-ttf \
    libxrender1 \
    libxext6 \
    xfonts-75dpi \
    xfonts-base

# Or use the official Odoo Docker image which includes these

8. Timeout on Large Reports

Reports with many pages (large invoices, stock picking lists) can timeout.

# In odoo.conf, increase the report timeout:
report_timeout = 120  # default is 60 seconds

Testing Reports

# Test wkhtmltopdf directly:
wkhtmltopdf --header-html header.html --footer-html footer.html \
  http://localhost:8069/report/html/account.report_invoice/1 test.pdf

# Check Odoo report rendering in debug mode:
# Add ?debug=1 to URL, then:
# Print > select report > check browser console for errors

Quick Diagnostic Checklist

1. Verify wkhtmltopdf version: wkhtmltopdf --version (need 0.12.6.1 patched)
2. Check Odoo logs for wkhtmltopdf errors when printing
3. Try the Standard document layout (eliminates custom template issues)
4. Verify company has a logo and address set
5. Check paper format margins vs header/footer height
6. In Docker: ensure X11 libraries and fonts are installed