Skip to content

Known Errors

Jump to bottom
DantePereyra edited this page Nov 20, 2025 · 3 revisions

PDF Reports Fail to Render Correctly (wkhtmltopdf issue)

When generating PDF reports in Odoo (e.g., quotations, invoices), you might encounter an issue where the report:

  • Appears blank
  • Is missing styles
  • Displays a login screen
  • Or fails to render entirely

This usually points to a misconfiguration in how Odoo exposes its web interface to wkhtmltopdf. The root cause often involves the report.url parameter.

Root Cause

Odoo uses wkhtmltopdf to generate PDF reports by converting HTML pages into PDF. Since wkhtmltopdf is an external binary, it must access Odoo's report views via an HTTP URL, just like a browser would.

If the URL it uses is not reachable from inside the container (or the server where wkhtmltopdf runs), the PDF generation fails.

Common Symptoms

  • PDF report is completely blank
  • Report is missing CSS or layout styles
  • A login screen appears in the generated PDF
  • PDF fails with a timeout or error message

Diagnosis

Check your Odoo system parameters:

  • Go to Settings → Technical → Parameters → System Parameters
  • Look for the parameter:
report.url
  • If it does not exist, Odoo will fall back to:
web.base.url

Check what URL is set. If it points to localhost, 127.0.0.1, or a domain that is not accessible from inside the Docker container, the rendering will fail.

✅ Solution

Add a new system parameter:

Key Value
report.url http://172.17.0.1:8169

Replace the value if your setup uses a different port or Docker bridge IP.

  • Why 172.17.0.1?

This is the default IP address of the Docker host as seen from inside Docker containers. If Odoo is running in a Docker container, this allows wkhtmltopdf to connect back to Odoo's web server.

  • How to confirm the IP?

Run this on your Docker host:

ip addr show docker0

You’ll see something like:

inet 172.17.0.1/16

This confirms the IP that containers can use to reach the host.

  • Reference Table
Parameter Purpose Fallback Notes
report.url Base URL for PDF rendering via wkhtmltopdf Optional Use it when web.base.url is not accessible from inside the container
web.base.url General base URL for external links Used if report.url is not set Must be reachable from wkhtmltopdf’s context

Error: The 'zope.event' distribution was not found and is required by gevent

Description:

This error occurs because the zope.event dependency required by the gevent package is not properly installed inside the container.

Solution:

Edit the Dockerfile at line 117 to ensure setuptools is explicitly upgraded by adding the following command:

RUN pip3 install --upgrade setuptools \

After making this change, remove the existing container and rebuild the image to apply the fix:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Prevention:

Keeping package management tools (pip, setuptools, wheel) up to date in the container image helps prevent dependency conflicts and missing package errors during future installations.

Missing 'phonenumbers' dependency

When installing 18.0 version you can encounter that missing dependency. It's easy to fix:

On Dockerfile, add phonenumbers before odoo instalation, on line 147.

then,

docker-compose down
docker-compose build --no-cache
docker-compose up -d

It should work again.

Clone this wiki locally