Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11If an SVG appears locally but disappears from a Heroku PDF, do not start by changing the SVG. First identify the exact wkhtmltopdf executable running in the dyno, then inspect the HTML that wicked_pdf actually gives it and verify every asset URL from that environment. Only after URLs load successfully should you test whether the deployed wkhtmltopdf build handles the SVG features you use.
wicked_pdf is a Rails wrapper; it invokes the external wkhtmltopdf renderer. Rails helpers cannot make an inaccessible URL available to that separate process, and different wkhtmltopdf builds can produce different results for features such as clip-path and opacity.
What the failure usually means
There are three distinct failure classes:
- The renderer cannot fetch the SVG. Relative paths, an incorrect host or protocol, missing production assets, authentication, or a dyno-inaccessible private URL can all result in a missing image.
- Another broken image is disrupting the page. The wicked_pdf documentation warns that one missing or wrongly referenced image can prevent other images from appearing, so an apparent SVG problem may be a wider asset problem.
- The deployed binary renders the SVG differently. wkhtmltopdf behavior depends on its exact version, Qt patch level and build. A documented issue reported differences in
clip-pathand opacity between an unpatched Qt 0.12.4 build and patched builds. That is a reason to compare binaries, not proof that every patched release fails.
These causes require different fixes. Record evidence in that order instead of changing several variables at once.
1. Record the binary and Heroku environment
Run diagnostics in a one-off dyno or the same process type that generates PDFs. The important value is the executable actually used at runtime, not a Gemfile entry or an old buildpack article.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
heroku run bash --app YOUR_APP
which wkhtmltopdf
wkhtmltopdf --version
uname -a
printenv | grep -E 'HEROKU|RAILS_ENV|RACK_ENV'Also determine the current Heroku stack in your app’s settings or with the Heroku CLI, and identify how the binary was installed (buildpack, system package, slug content or a custom release). Keep the complete version string, including whether it says “with patched qt”. Two binaries that both report 0.12.x are not necessarily equivalent.
If wkhtmltopdf is not on PATH, configure wicked_pdf with the real path. In an initializer, use the path supported by the version of the gem in your application:
WickedPdf.config = {
exe_path: '/app/vendor/bin/wkhtmltopdf'
}Use the path returned by which, and restart the dyno after changing configuration. Do not infer a working path from local development.
2. Inspect the exact HTML wicked_pdf renders
Turn on wicked_pdf’s debug HTML mode for the failing action (the option is commonly called show_as_html). Open the resulting HTML and inspect the actual <img>, inline SVG, CSS and stylesheet URLs. You are looking for what wkhtmltopdf receives, not what your Rails view source appears to contain.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
format.pdf do
render pdf: 'invoice', show_as_html: true
endDebug mode has an important trap: wicked_pdf helpers can emit file:/// references there. A normal browser may block or handle those differently from the renderer. Use the regular image helper path documented by wicked_pdf when inspecting the debug page, and separately test the URL that the PDF process will fetch.
Check:
- The SVG URL is absolute, including scheme and host, or is generated by wicked_pdf’s asset/image helpers.
- The host resolves from a Heroku dyno and does not require a browser session, VPN or local DNS entry.
- The protocol is the one your production endpoint serves. Do not “fix” this by stripping HTTPS; an old community workaround was version-specific and unsafe as a general recommendation.
- Production assets are precompiled and present in the slug or served from a reachable asset host.
- CSS references, fonts, masks, filters and external SVG references also resolve. A visible SVG can still depend on a missing stylesheet or font.
- Every image on the page has a valid URL. Fix all broken references before deciding SVG itself is unsupported.
3. Make asset references deterministic
Use absolute URLs
For a remotely served asset, generate a fully qualified URL with the production host and protocol. Configure Rails’ asset host and default URL options for the environment that creates the PDF, then verify the generated HTML contains that value. A relative /assets/logo.svg can work in a browser while failing when wkhtmltopdf runs outside the request context.
Use wicked_pdf helpers where appropriate
Replace hand-written relative paths with the documented wicked_pdf_image_tag and asset helpers. These helpers are designed to produce references suitable for the renderer, but you still must confirm the final URL and its availability from Heroku.
Precompile or inline deliberately
Precompile the SVG and its dependent assets for production, and verify the compiled filename (including any digest) appears in the HTML. For a small, self-contained SVG, inline base64 data can remove a network dependency. The wicked_pdf documentation notes the trade-off: inlining increases HTML size and can hurt performance, so it is not a blanket solution for large illustrations or many pages.
Test access from the dyno
Use a one-off dyno to request the exact URL copied from the debug HTML:
curl -I -L 'https://assets.example.com/packs/logo-ABC123.svg'
curl -L --fail --silent --show-error 'https://assets.example.com/packs/logo-ABC123.svg' -o /tmp/logo.svg
file /tmp/logo.svg
head -c 200 /tmp/logo.svgA successful HTTP status is not enough: inspect redirects, content type and the downloaded bytes. An HTML login page saved as .svg is still a broken asset. If the URL requires headers or cookies, make those requirements explicit in the PDF request or serve a suitable public asset.
4. Reduce the SVG to a controlled reproduction
Create a minimal HTML file containing one inline or local SVG with a basic rectangle or path. Render that file with the deployed executable, then add one feature at a time:
- Basic shape and solid fill.
- External image or stylesheet reference.
- Opacity.
clipPathor masks.- Filters, embedded fonts and other effects used by the production artwork.
Keep the SVG and HTML available on the dyno, or use the same absolute URLs as production. Compare the PDF generated by the Heroku binary with the PDF from your local binary, recording both complete version strings. If the basic shape works but one feature disappears, you have a renderer compatibility case rather than an asset-host problem.
The wkhtmltopdf issue describing clip-path and opacity differences is a report from one environment, not an exhaustive compatibility matrix. Treat each feature as a hypothesis and preserve the smallest reproducer that demonstrates it.
5. Compare or change the Heroku binary carefully
Only change the deployment binary after URL and HTML checks pass. Compare these axes:
| Axis | What to record | Why it matters |
|---|---|---|
| Renderer | Full wkhtmltopdf --version output |
Patch level and Qt variant affect SVG behavior. |
| Operating environment | Heroku stack, OS details and shared-library availability | A binary built for another stack may not run or may behave differently. |
| Input | Minimal HTML, SVG and all dependent assets | Removes application noise from the comparison. |
| Required features | clip-path, opacity, filters, fonts and external references | Different features can fail independently. |
| Output | Rendered PDF from each exact binary | Visual comparison confirms whether a change helped. |
Old Heroku Elements pages describe historical configurations: one heroku-18 listing used a fixed 0.12.5-1.bionic_amd64.deb, while another older listing described 0.12.3 with Cedar-14/Heroku-16 requirements. Those pages are configuration history, not current installation instructions. Confirm your app’s present stack, the buildpack’s availability and the binary’s compatibility before adopting any recipe. After a change, regenerate the same minimal PDF and the real document, then compare output and logs.
Prefer a controlled fallback when fidelity is essential
If a required SVG feature is not rendered by the available wkhtmltopdf build, simplify that artwork for PDF (for example, replace a complex effect with a pre-rendered image) or choose a renderer whose documented feature set matches your needs. Keep the original SVG for browser output and a PDF-specific variant when necessary; do not silently accept a degraded logo, chart or signature.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →6. Capture useful logs and failure evidence
Run wkhtmltopdf with an error log enabled where your integration permits it, and preserve the generated HTML, SVG and command-line version. Record HTTP redirects, timeouts and asset response bodies. A useful report includes:
- Exact wkhtmltopdf version and Qt/build variant.
- Heroku stack and operating-system version.
- wicked_pdf and Rails versions.
- The smallest HTML/CSS/JS and SVG that reproduces the failure.
- Expected versus actual PDF output, including which SVG features disappear.
- Whether the same files render locally and which local binary was used.
This matches the wkhtmltopdf support guidance, which asks for the version, operating system and a detailed reproducing test case.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common symptoms and fixes
| Symptom | Likely cause | Next action |
|---|---|---|
| All images, including SVG, are absent | Wrong host/protocol, missing precompiled assets or inaccessible URLs | Inspect debug HTML and fetch every URL from a dyno. |
| One SVG is absent but PNGs work | SVG URL, MIME/redirect problem or unsupported SVG feature | Download that SVG, test a basic shape, then add features incrementally. |
| The debug page shows a broken image | file:/// helper output or an invalid debug reference |
Use the normal wicked_pdf image helper path and inspect the PDF HTML separately. |
| Works locally, fails only on Heroku | Different binary, Qt patch, stack or asset reachability | Capture both --version outputs and compare from identical HTML. |
| Changing HTTPS to HTTP appears to help | Historical, version-specific behavior or a redirect issue | Keep HTTPS, inspect redirects/certificates and fix the actual URL or binary issue. |
| Basic SVG works; clip-path or opacity does not | Build-specific renderer behavior | Keep a minimal reproducer and evaluate a compatible binary or simplified artwork. |
| Changing the buildpack makes wkhtmltopdf fail to start | Stack/shared-library mismatch | Revert, verify stack compatibility and use the executable path reported in the dyno. |
Or skip the browser setup
If your goal is a clean screenshot of the rendered page rather than a Rails PDF pipeline, ScreenshotNeo provides a website screenshot API and MCP server. It accepts the page as a visitor, removes cookie-consent banners, newsletter popups and chat widgets before capture, and reports whether the page was cleanly captured. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed.
One request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete request options in the ScreenshotNeo documentation. The same call from Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)And Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also offers an MCP server for AI agents, including Claude, Cursor and other MCP clients, with tools for screenshots, page information and PDF capture. Every feature is on every plan: 1,000 screenshots per month are free with no card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Best Value
Frequently Asked Questions
Should I change the SVG file first?
No. First prove that the deployed process can fetch the exact asset and identify the wkhtmltopdf build. Editing artwork before those checks can hide the real cause.
Can a Rails asset helper alone solve a Heroku PDF problem?
No. The helper can generate a suitable reference, but the external wkhtmltopdf process still needs a reachable URL or embedded data.
Is there one wkhtmltopdf version that is guaranteed to render every SVG?
No universal guarantee is established. Compatibility depends on the concrete build, Qt variant, environment and SVG features, so test the binary used by your dyno.
Recommended Free Tools
What should accompany a bug report?
Include the complete renderer version, operating system and Heroku stack, wicked_pdf/Rails versions, minimal HTML and SVG, and the expected and actual output.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
