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.
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_pathandchromium_path, and runbench setup-chromein 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.
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.
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.
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 #40334 | Print Designer chromium-path family | |
|---|---|---|
| Symptom | Hangs 60–120s, then 504 Gateway Time-out | Fails instantly — ValidationError, no hang |
| Error string | IsADirectoryError: [Errno 21] Is a directory | Chromium is not downloaded. Please run the setup first. |
| Root cause | Containment root loosened to public/; directory reaches read_file and kills the CDP reader | chromium_binary_path vs chromium_path config-key mismatch |
| Affected versions | frappe v16.24.0, v16.24.1, v16.24.2 only | Any version with Print Designer installed and only chromium_path set |
| Fix | Upgrade 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 2026 | No — 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 #40098 | Frappe core version is irrelevant to this one |
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 | |
|---|---|
| Symptom | Chrome PDF spins for 60 to 120 seconds, then 504; a blank print format fails too |
| Fingerprint | Error Log row WebSocket listening error: with IsADirectoryError: [Errno 21] |
| Affected | Frappe v16.24.0, v16.24.1, v16.24.2 (and version-16-hotfix from 18 to 28 June 2026) |
| Workaround | PDF Generator → wkhtmltopdf on the Print Formats you use, bench restart, reap orphaned Chromium |
| Fix | Frappe 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.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 5 August 2026
Worked with us? Leave a Google review