Skip to main content

ERPNext how-to & fixes

Frappe v16 Chrome PDF 504: the v16.24 bug that hangs your gunicorn worker

Every Chrome PDF returns 504 on Frappe v16.24.0 to v16.24.2: a directory path kills the CDP reader and blocks the worker. The fix is v16.24.3.

Updated 12 Oct 202611 min readBy ManojFirst published 5 Aug 2026

You click Print → PDF on a Sales Invoice. The tab spins for a minute or two. Then: 504 Gateway Time-out. Every format does it, including a blank one. This is frappe issue #40334, and it affects exactly three releases: v16.24.0, v16.24.1 and v16.24.2. A path-containment check loosened by PR #40099 let Chrome's setup navigation resolve to the public directory; frappe.read_file() raised IsADirectoryError; that exception killed the DevTools websocket reader; and the untimed CDP call blocked your gunicorn worker until it was SIGKILLed. The fix is PR #40365, released in v16.24.3 on 28 June 2026. This post gives the version boundary, the workaround and the upgrade, and shows how to tell this bug from the Print Designer chromium-path bug it is often confused with.

I lead ERPNext and Frappe implementations at MithTech, a team of Frappe specialists in Bengaluru. With this bug the expensive part is not the fix; it is the time a team spends chasing "Perhaps out of memory?" in the gunicorn log, which is stock wording and means nothing here.

Which Chrome PDF bug do you actually have?

Two unrelated Chrome-PDF failures circulate in the Frappe community, and forum threads and AI answers often merge them. They have different root causes, different fixes and, what matters most in operations, different release status. One is fixed and shipped. The other is fixed on a branch and, as of 12 October 2026, has not been released.

Interactive

Which Chrome PDF Bug Do I Have?

Pick your exact symptom, enter your frappe version, and say whether Print Designer is installed. The decider routes you to the correct root cause, the concrete fix, the current release status of that fix, and the real issue links — keeping frappe #40334 strictly separate from the Print Designer chromium path-key family.

1 · What exactly happens when you hit Print → PDF?

3 · Is Print Designer installed?

Pick a symptom to get a verdict. The two failure families look identical from the Desk UI and have completely different fixes.

Print Designer ships its own fork of the Chromium stack that never took the change behind #40334, so it is structurally immune to it. Answering “yes” above changes the diagnosis, not the blame.

The short version:

If your PDF hangs for a minute then 504s, it is frappe #40334 → upgrade to v16.24.3 or newer. If your PDF fails instantly with "Chromium is not downloaded", it is the Print Designer binary-path family → set chromium_binary_path and chromium_path, and run bench setup-chrome in every container that prints.

What is the version boundary, proved rather than assumed?

Many write-ups say "v16.24.1 and v16.24.2 are broken". That is one release short. The regression commit 235c12a369, the backport of PR #40098 onto version-16-hotfix as PR #40099 (merged 18 June 2026), is an ancestor of v16.24.0 (released 24 June 2026), and v16.24.0's release notes describe it in plain language: PDF creation now accepts files from the site's public folders, not just the folder used for uploads. That loosening is the bug.

Interactive

v16.24 Version Timeline

The v16.24.x release sequence with the broken window marked, the regression PR and fix PR called out with their commit hashes, and a live verdict for any version you type in — including the branch-tracker case where you are on version-16-hotfix rather than a tag.

Broken releases3
Fixed fromv16.24.3
Days broken (tags)4
  • v16.23.122 Jun 2026UnaffectedLast release before the regression
  • v16.24.024 Jun 2026Chrome PDF brokenFirst release carrying commit 235c12a369 (PR #40099) — its own release notes credit it
  • v16.24.125 Jun 2026Chrome PDF brokenThe version in the original bug report
  • v16.24.227 Jun 2026Chrome PDF brokenFrappe Cloud sites were pinned here when it hit
  • v16.24.328 Jun 2026FixedEmergency patch — commit 63a94104ce (PR #40365). Cut specifically for this bug
  • v16.24.41 Jul 2026FixedCarries the fix
  • v16.25.01 Jul 2026FixedNext minor off the same lineage
RegressionPR #40099 · 235c12a369“fix: loosen check for local resources” — backport of #40098, merged to version-16-hotfix on 18 Jun 2026.
FixPR #40365 · 63a94104ce“fix(chromium): skip directory paths in local resource interceptor” — merged to version-16 on 28 Jun 2026. Regression tests followed in #40634.

Enter a version

Paste the output of `bench version` — for example `frappe 16.24.1 version-16-hotfix`.

Ancestry above is from GitHub’s compare API, not inference: 235c12a369 is an ancestor of v16.24.0 onward, and 63a94104ce is an ancestor of v16.24.3 onward.

Two footnotes that catch people out:

If you track the version-16-hotfix branch instead of a tag, your broken window is wider: 18 June 2026 (when #40099 merged) to 28 June 2026 (when the fix merged as #40364). Ten days, not four.

The develop (v17) line got the guard first. The same one-line guard landed on develop on 25 June 2026 inside PR #40295, a large print-format-builder PR that happened to include it. That PR was not backported to v16, which is why the v16 hang lasted three more days and needed its own release.

Why does a PDF bug kill an entire worker?

A failing PDF should return an error. Instead it takes a gunicorn worker with it. The chain is worth understanding because it explains why the timeout knob does not help.

Interactive

Hang Anatomy

An eight-step walkthrough of the failure chain, from Chrome's setup navigation to the bare site URL, through the loosened containment check and the IsADirectoryError, to the dead CDP reader, the unresolvable future, the gunicorn SIGKILL and the 504 your browser finally shows.

Step 1 of 8

Chrome navigates to your bare site URL

During PDF page setup, frappe points the body, header and footer pages at get_host_url() — the site root, with no path component.

This happens before your print format HTML is rendered. That is why even a blank format fails: the bug is in setup, not in your template.

Traceback line numbers vary between checkouts, so we describe the call chain rather than quoting line numbers as canonical.

The most useful line in the chain is the Error Log title: WebSocket listening error:. That row is the fingerprint. Its body carries IsADirectoryError: [Errno 21] Is a directory, pointing at your site's public folder.

A note on line numbers: the traceback pasted into the GitHub issue came from the reporter's exact checkout and its line numbers differ slightly from the live v16.24.3 source. Match on the call chain and the exception, not on line numbers.

A note on the timeout: reporters cite "60 seconds", and you will see 60 quoted widely. Bench's default http_timeout is 120, and that one key drives both gunicorn's -t and nginx's proxy_read_timeout. 60 seconds is a per-deployment override common in hosted and Docker stacks: real, but not the default.

How do you fix it?

Code recipe

Chrome PDF Recipe

Three tabs with copy buttons: the immediate wkhtmltopdf workaround with the exact navigation paths and its caveats, the permanent version bump plus a one-line cherry-pick for teams that cannot take a release bump, and a verification routine that actually proves the fixed code is running.

Get printing again in minutes without touching the frappe version. The catch most guides miss: the effective generator is read from the Print Format record, not from Print Settings — so changing the global setting alone does nothing. Set both.

bench console
# 1) UI route (do both — the second one is what actually takes effect)
#
#    Global:      Awesome Bar -> "Print Settings" -> PDF Settings section
#                 -> PDF Generator -> wkhtmltopdf -> Ctrl+S
#                 (menu route: Home > Settings > Print Settings)
#
#    Per format:  Awesome Bar -> "Print Format" list -> open the format
#                 you actually print with -> PDF Generator -> wkhtmltopdf
#                 -> Save. Repeat for every format in use.
#                 (Or select-all in the list view -> Edit -> PDF Generator.)

# 2) Same thing from the CLI, for every format still on chrome:
bench --site yoursite console

>>> frappe.db.get_value("Print Settings", None, "pdf_generator")
>>> stuck = frappe.get_all("Print Format",
...     filters={"pdf_generator": "chrome"}, pluck="name")
>>> for pf in stuck:
...     frappe.db.set_value("Print Format", pf,
...         "pdf_generator", "wkhtmltopdf")
>>> frappe.db.commit()

# 3) Clear the wedged state — reverting the setting does NOT free
#    workers that are already blocked.
bench restart
sudo supervisorctl restart all          # if workers are still pinned
pkill -f chromium-headless-shell        # reap orphaned browsers

# CAVEATS
# - download_pdf accepts ?pdf_generator=chrome. Any bookmark, custom
#   button or integration carrying that param still hits Chrome.
# - wkhtmltopdf uses an old Qt WebKit engine: no modern flexbox/grid,
#   different font metrics and page breaks. Formats authored against
#   the Chrome renderer will visibly shift.
# - This is a stopgap. wkhtmltopdf is unmaintained upstream.

0 of 5 steps done

Tick a step’s number when it is done; the ticks stay on this device.

Confirm it is #40334 before you change anything

Print a blank format with the chrome generator. If that also 504s, the failure is in page setup. Then search the Error Log for IsADirectoryError or the title WebSocket listening error:. Two positives and you are done diagnosing.

Buy yourself time with wkhtmltopdf

Set PDF Generator to wkhtmltopdf on the Print Format records you actually print with: that field, not the global one, is what the resolution code reads. Set the global in Home > Settings > Print Settings as well. Then bench restart.

Clear the wedged state

Reverting the setting does not release workers that are already blocked. bench restart, then sudo supervisorctl restart all if workers are still pinned, then pkill -f chromium-headless-shell to reap the orphaned browsers that the SIGKILLed workers left behind.

Upgrade past the window

Get to v16.24.3 or newer. bench update --reset is the standard route; checking out the tag and running bench setup requirements, bench build --app frappe and bench --site all migrate is the frappe-only route. On Docker, bump the image tag and redeploy; do not patch inside a running container. On Frappe Cloud, update the bench group.

Verify, then switch back to chrome

Grep frappe/utils/pdf_generator/page.py for os.path.isfile(final_system_path). One hit means the guard is present. Confirm the Error Log has stopped collecting IsADirectoryError rows, request one chrome-generated PDF and expect a 200 in a couple of seconds. Then move your print formats back off wkhtmltopdf, which is unmaintained upstream and renders modern CSS badly.

Is Print Designer causing this?

No, and this is where most of the confusion sits.

Print Designer registers its own pdf_generator in hooks.py and ships a fork of the CDP stack. Its before_request hook intercepts download_pdf and printview and serves them through its own generator entirely. Its forked page.py still uses the pre-#40098 prefix check — it only accepts paths starting with assets/ or files/. An empty root path fails both, falls straight through to continueRequest, and the directory can never reach read_file. Print Designer never inherited the regression because it never took the change.

So the often-cited "Print Designer breaks Chrome PDF" issues, print_designer #437, #432, #407 and frappe_docker #1821, are a separate bug family. Three of them predate the v16.24.0 regression by more than a year, so they cannot be the same bug.

The core of that family is a config-key mismatch. Frappe core looks up chromium_path in the common site config. Print Designer's released code looks up chromium_binary_path. A site configured the core way starts throwing "Chromium is not downloaded" as soon as Print Designer is installed: installing it breaks Chromium PDF generation that worked before, which is what frappe_docker #1821 says in its title.

The status that matters: print_designer PR #523, which makes Print Designer fall back to chromium_path, was merged to develop on 7 May 2026, but the latest tagged Print Designer release on 12 October 2026 is still v1.6.7 from 10 February 2026. No released version of Print Designer contains that fix yet. Set both config keys and keep them set.

frappe #40334Print Designer chromium-path family
SymptomHangs 60–120s, then 504 Gateway Time-outFails instantly — ValidationError, no hang
Error stringIsADirectoryError: [Errno 21] Is a directoryChromium is not downloaded. Please run the setup first.
Root causeContainment root loosened to public/; directory reaches read_file and kills the CDP readerchromium_binary_path vs chromium_path config-key mismatch
Affected versionsfrappe v16.24.0, v16.24.1, v16.24.2 onlyAny version with Print Designer installed and only chromium_path set
FixUpgrade frappe to v16.24.3+ (PR #40365)Set both config keys; bench setup-chrome in every printing container
Fix released?Yes — v16.24.3, 28 Jun 2026No — PR #523 merged to develop 7 May 2026; latest release v1.6.7 (checked 12 Oct 2026)
Does the other app matter?Print Designer is immune — it never took #40098Frappe core version is irrelevant to this one
Two Chrome-PDF failures that are often confused: different causes, different fixes, different release status

What else should you know before you touch production?

The ?pdf_generator=chrome escape hatch. The download_pdf endpoint accepts an explicit query parameter, and it wins over your doctype settings. Any bookmark, custom button, or integration carrying that param will still hit Chrome no matter what you set in Print Settings. Grep your customisations before you declare the workaround complete.

wkhtmltopdf is a stopgap, not a destination. It renders on an old Qt WebKit engine: no modern flexbox or grid, different font metrics, different page breaks. Formats built for the Chrome renderer will visibly shift. It is also unmaintained upstream, and Frappe's v16 notes say classic print formats stop working in v17. Use it to stop the bleeding, then go back to chrome once you are on v16.24.3+.

If wkhtmltopdf in Docker fails with a ConnectionRefusedError instead, that is a URL your container cannot open, not this bug: see the fix.

Orphaned Chromium processes are a real second-order cost. Because SIGKILLed workers never clean up, every retry leaves a chromium-headless-shell behind and RAM climbs. Frappe's own source carries a # TODO: close browser when worker is killed. comment: a known nearby problem, not something you introduced.

The pdf_generator field is undocumented. It exists on both the Print Settings and Print Format doctypes, but when we checked (August 2026) no docs.frappe.io page documented it. The only official description of the chrome generator's behaviour is release-notes prose and the source.

Multi-container Docker stacks need Chromium everywhere. Frappe enqueues bulk print jobs to the workers, so queue-short and queue-long need a reachable Chromium binary too — not just backend. That is a separate open problem, and the one most likely to bite after you have fixed everything else. That is why we treat printing infrastructure as part of the deployment checklist on the sites we host and run.

At a glance

What to know
SymptomChrome PDF spins for 60 to 120 seconds, then 504; a blank print format fails too
FingerprintError Log row WebSocket listening error: with IsADirectoryError: [Errno 21]
AffectedFrappe v16.24.0, v16.24.1, v16.24.2 (and version-16-hotfix from 18 to 28 June 2026)
WorkaroundPDF Generator → wkhtmltopdf on the Print Formats you use, bench restart, reap orphaned Chromium
FixFrappe v16.24.3 or later (PR #40365)
Not this bug"Chromium is not downloaded" at once: the Print Designer path-key family

Frequently asked questions

Why does ERPNext PDF download give a 504 Gateway Timeout?

On frappe v16.24.0 through v16.24.2, the Chrome PDF generator's local-resource interceptor tries to read your site's public directory as if it were a file. The resulting IsADirectoryError kills the CDP websocket reader task, and because the synchronous CDP send has no timeout, the gunicorn worker then blocks forever on a response that will never arrive. Gunicorn SIGKILLs the worker at http_timeout and nginx serves the 504. Upgrade to v16.24.3 or newer.

Which version of Frappe fixes the Chrome PDF 504 error?

v16.24.3, published 28 June 2026, via PR #40365 (commit 63a94104ce). v16.24.0, v16.24.1 and v16.24.2 are all broken — note that v16.24.0 is included, which is wider than most write-ups claim. Anything from v16.24.3 onward, including v16.24.4 and v16.25.0, contains the fix.

Why is my ERPNext invoice PDF not downloading?

If it spins for about a minute and then shows a 504 error page, you are almost certainly on frappe v16.24.0, v16.24.1 or v16.24.2 with the Chrome PDF generator. Switch the print format you use to wkhtmltopdf for immediate relief, then update frappe to v16.24.3 or later and switch back.

Is the ERPNext Chrome PDF bug fixed yet?

Yes. Frappe issue 40334 was opened on 26 June 2026 and closed roughly forty hours later on 28 June, with the fix shipping the same day in version 16.24.3. Regression tests shipped alongside it, and further tests landed on the development branch in PR #40634, so it should not come back silently.

What does IsADirectoryError Errno 21 mean in Frappe PDF generation?

It means the PDF code called frappe.read_file() on sites/<yoursite>/public, which is a folder, not a file. It happens because Chrome navigates to your bare site URL during PDF page setup, the stripped path is empty, and the loosened path-safety check wrongly approves it. The v16.24.3 fix adds an os.path.isfile() condition to that guard.

Does Print Designer cause the ERPNext Chrome PDF timeout?

No. Print Designer ships its own fork of the Chromium stack that never took the change behind #40334, so it is structurally immune to it. Print Designer has a different Chrome problem: it reads the config key chromium_binary_path while frappe core reads chromium_path, so it fails instantly with "Chromium is not downloaded" instead of hanging. Set both keys. The upstream fix for that one is merged to develop but, as of 12 October 2026, not in any tagged release (latest: v1.6.7).

Will raising http_timeout fix the ERPNext PDF timeout?

No. The worker is blocked on a future that nothing will resolve, because the task that would resolve it has died. Raising http_timeout only makes users wait longer for the same 504; lowering it recycles wedged workers faster. Bench's default is 120 seconds, not the often-quoted 60, which is a common per-deployment override.

What happens if we don't upgrade past v16.24.2?

Every Chrome-generated PDF stays broken: invoices, delivery notes, quotations, statements. Each attempt holds a gunicorn worker until gunicorn kills it, so concurrent PDF attempts starve the web workers and slow the whole site, and each killed worker leaves a Chromium process using RAM. Staying on wkhtmltopdf is possible but means an unmaintained renderer and visibly different output.

None of the forum threads above reports this specific regression; we checked each one. The bug was filed on GitHub and fixed within two days. That is why it is worth writing down: the fix is trivial, the diagnosis is not, and the story keeps getting merged with a different bug whose fix has not been released.

Your next step

Stuck on a v16 upgrade that broke something you did not expect?

ERPNext how-to & fixes

Now see what an audit finds in yours

When the same problems keep coming back, tick what you see and get an audit of the ERPNext you have, then fixes in order of what costs you most.

Comments & ratings

No comments yet. Start a new discussion.

0

Manoj · Published on 5 August 2026

Worked with us? Leave a Google review

Questions about this? Talk to the team.

Book a 30-minute Google Meet, WhatsApp us, or send a message. The engineer who works on this replies.

Send us a message

Your details go to our team's CRM and are used only to reply.