Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Wicked PDF does not render HTML itself. It launches the external wkhtmltopdf program, so a working Rails gem is only one part of a working PDF pipeline. Fix runtime errors by checking, in order, the Bundler environment, the executable path, first-run extraction permissions, the operating system loader, temporary storage, fonts, and asset URLs.
What the error actually means
Wicked PDF is a Rails wrapper around the shell utility wkhtmltopdf, which converts HTML into a PDF for the user. The project documentation recommends adding gem 'wkhtmltopdf-binary' and configuring an initializer when the executable is not on the web server’s PATH. Installing the gem does not prove that the Rails process can activate the gem, execute its binary, load its shared libraries, or write its temporary files.
Messages such as PDF could not be generated, cannot find wkhtmltopdf, or an exit status of 127 identify different layers of failure. Exit 127 commonly means the command or its dynamic loader could not be started; it does not necessarily mean your view template is invalid.
1. Verify the deployed Bundler environment
Run this in the same release directory, container, user account, and deployment environment that starts Rails:
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
bundle exec ruby -e 'puts Gem.loaded_specs["wkhtmltopdf-binary"]&.full_gem_path'A successful result prints the installed gem directory. A blank result means the gem is not activated in that bundle. A reported failure found that wkhtmltopdf-binary was absent from the deployed bundle even though /bin/wkhtmltopdf existed on PATH. Check all of the following before changing application code:
- The gem is in the correct
Gemfilegroup and is not excluded by deployment settings. Gemfile.lockis committed and installed in the release.- The command is run with the same Ruby and Bundler versions used by the Rails service.
- The service account sees the same environment as your interactive shell.
PATH visibility and Bundler activation are separate checks. You need the executable available to the process and the Ruby gem or Wicked PDF configuration that resolves it.
2. Find the path Wicked PDF is really using
From a Rails console in the deployed environment, inspect Wicked PDF’s resolver:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
WickedPdf.new.send(:find_wkhtmltopdf_binary_path)If the returned path is absent or incorrect, set an explicit path in an initializer such as config/initializers/wicked_pdf.rb:
WickedPdf.configure do |c|
c.exe_path = '/usr/local/bin/wkhtmltopdf'
c.enable_local_file_access = true
endReplace the example with the path that exists in your image or host. Confirm it is executable:
command -v wkhtmltopdf
ls -l /usr/local/bin/wkhtmltopdf
/usr/local/bin/wkhtmltopdf --versionIf command -v finds a different copy than the one configured, you may be debugging one binary while Rails launches another. Restart the application after changing the initializer so every worker loads the new value.
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
3. Account for wkhtmltopdf-binary’s first-run extraction
The binary gem ships compressed, platform-specific executables and unpacks the selected executable into its gem directory on first use. The process user therefore needs write permission to that directory until extraction completes. This is especially important in containers and read-only deployments.
Free tools Windows power users keep installed
One-click scans. No signup required.
Symptoms
- The first PDF request fails, while later requests work after a manual extraction.
- The gem directory is owned by the build user but Rails runs as
www-data,app, or another restricted account. - A read-only filesystem produces a permission or extraction error before rendering begins.
Fix
- Identify the gem directory with the Bundler command above.
- During image build or release preparation, allow the runtime user to write there long enough for extraction.
- Alternatively, perform a controlled warm-up as the same user that serves Rails, then make the resulting executable readable and executable.
- Do not solve this by granting broad write access to the whole application tree; limit ownership or permissions to the required gem and temporary locations.
After extraction, verify that the resolved executable can be launched by the service account, not merely by root.
4. Diagnose exit 127 before changing PDF options
On Alpine and other minimal images, a binary can exist and have execute permission yet still fail immediately because its dynamic loader cannot find a required library. One reported 0.12.5 failure on Alpine with OpenSSL 3 referenced missing libssl.so.1.1 and libcrypto.so.1.1. In that situation, Wicked PDF HTML options cannot help: rendering never starts.
Check the binary and loader
/path/to/wkhtmltopdf --version
ldd /path/to/wkhtmltopdfLook for “not found” libraries or an interpreter that is unavailable in the base image. Check the image’s libc and OpenSSL versions as well as the binary’s build target.
Choose a compatible repair
- Use a wkhtmltopdf build compiled for the distribution and libc in your image.
- Install the ABI libraries required by that build, where your distribution supports them.
- Use a supported distribution package or a base image whose loader and OpenSSL ABI match the binary.
- Pin the same image and package versions in CI and production instead of mixing a binary from one distribution with another distribution’s runtime.
There is no single compatibility matrix covering every Ruby, Rails, Alpine, libc, and OpenSSL combination. Treat the binary’s provenance, target distribution, and shared-library requirements as deployment inputs that must be verified together.
5. Check temporary directories and process permissions
Wicked PDF and the underlying executable need a writable temporary location. The maintainer troubleshooting guidance specifically recommends checking ENV['TMPDIR'] and tempfile-directory writability.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
bundle exec ruby -e 'p ENV["TMPDIR"]; d = Dir.tmpdir; p [d, File.writable?(d)]'In a shell, also inspect the directory configured by your service manager or container:
echo "$TMPDIR"
ls -ld "${TMPDIR:-/tmp}"
touch "${TMPDIR:-/tmp}/wicked-pdf-write-test" && rm "${TMPDIR:-/tmp}/wicked-pdf-write-test"Fix ownership, mount options, or the TMPDIR value for the Rails service. A directory that is writable in an interactive shell may not be writable by the systemd, Docker, or Kubernetes user that handles requests.
6. Install fonts and rendering dependencies
Even after the executable starts, the output can be blank, reflowed, or missing text when runtime rendering dependencies are absent. The wkhtmltopdf project notes dependence on Fontconfig and FreeType 2. Install the fonts your documents actually use and verify the font configuration in custom images.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems- Install a package set containing Fontconfig and FreeType 2 for your distribution.
- Copy required font files into the image and refresh the font cache when appropriate.
- Set
FONTCONFIG_PATHor the equivalent configuration when using a nonstandard font directory. - Test with a document containing the same scripts and weights as production (for example, accented Latin, CJK, or right-to-left text).
Missing fonts generally produce a rendering-quality problem rather than a “cannot find executable” error, so test them after the process can successfully report its version.
7. Make CSS, JavaScript, and images reachable
wkhtmltopdf runs outside the Rails process. Relative asset paths that work in a browser can fail when the converter receives a generated HTML document. Use absolute URLs or Wicked PDF’s asset helpers, and ensure the converter can reach the host over the network.
- Use the
wicked_pdf_stylesheet_link_tag,wicked_pdf_javascript_include_tag, andwicked_pdf_image_taghelpers where appropriate. - Prefer fully qualified HTTPS URLs when assets are served separately.
- Check authentication, private DNS, TLS certificates, and firewall rules from the application container.
- Inspect every image and stylesheet URL; the README warns that one missing image can affect other images.
When local files are intentionally required, the initializer example enables local file access. Do not enable it blindly for untrusted HTML; local-file access changes what the converter can read from the host.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
A repeatable production checklist
- Run the Bundler lookup under the deployed Rails user.
- Inspect
find_wkhtmltopdf_binary_pathin a Rails console. - Set
c.exe_pathexplicitly when auto-detection is unreliable. - Run
wkhtmltopdf --versionas the service account. - Use
ldd(or the platform equivalent) to find missing loader libraries. - Confirm first-run extraction and executable permissions.
- Confirm
TMPDIRand tempfile-directory write access. - Install and configure fonts and FreeType/Fontconfig.
- Open generated asset URLs from the same runtime network.
- Pin the resulting binary, base image, packages, and configuration in CI and production.
Or skip the browser setup
If your goal is a clean image or PDF of a web page rather than a Rails-specific HTML-to-PDF pipeline, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; failed loads, bot checks or CAPTCHAs, blank pages, timeouts, and cache hits are not billed. Responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)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}`);See the complete parameter reference in the ScreenshotNeo documentation. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Common failure symptoms and fixes
| Symptom | Likely layer | Action |
|---|---|---|
| Gem lookup is blank | Bundler deployment | Install and lock wkhtmltopdf-binary in the bundle used by Rails. |
| Executable not found | Path resolution | Inspect the resolver and set c.exe_path to the actual executable. |
Exit 127 with missing libssl or libcrypto |
Dynamic loader/ABI | Use a compatible binary, libraries, or base image. |
| Permission error on first request | Gem extraction | Allow the service user to unpack the platform binary once. |
| Tempfile or empty-output error | Filesystem | Fix TMPDIR and temporary-directory permissions. |
| PDF starts but images or CSS are missing | Assets/network | Use absolute or Wicked PDF helper URLs and verify runtime reachability. |
| Text is absent or substituted | Fonts | Install required fonts, Fontconfig, and FreeType; verify font paths. |
FAQ
Does installing wkhtmltopdf on the host replace wkhtmltopdf-binary?
No. A host executable can satisfy PATH lookup, while the deployed Ruby bundle still lacks the gem or resolves a different binary. Verify both independently.
Should I change Wicked PDF view options when the command exits 127?
No. Exit 127 and missing shared libraries occur before HTML rendering. Repair the executable, loader, ABI, or base image first.
Why does the first request fail only in production?
Production often runs as a restricted user or on a read-only filesystem, preventing the binary gem’s first-use extraction. Pre-extract it or grant narrowly scoped write access during initialization.
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 & 11Can local file access fix missing web images?
Only when the assets are local files and the security implications are acceptable. For web assets, use reachable absolute URLs or Wicked PDF helpers instead.
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.
