Free tools Windows power users keep installed
One-click scans. No signup required.
“RuntimeError: Location unknown” usually means Wicked PDF cannot find or execute the external wkhtmltopdf program. Confirm the path Rails resolves, install a compatible executable, and set an absolute exe_path in the Wicked PDF initializer. If the path is valid but execution reports a missing shared library, repair the operating-system dependency instead; that is a different failure from Rails route or template rendering.
What the error means
Wicked PDF does not render a PDF inside the Rails process. It launches the command-line wkhtmltopdf executable, passes it HTML and options, then reads the generated PDF. “Location unknown” is therefore a binary-discovery or process-execution problem before your view is rendered successfully.
The same symptom can have several causes:
- The executable is not installed on the host.
- It is installed, but the Rails service account cannot see it on
PATH. - Bundler resolves a shim or wrapper rather than the real executable.
- The configured path is stale, relative, or wrong for the current deployment.
- The file exists but lacks execute permission.
- The executable starts and then fails because a required shared library is missing.
Separate these cases before changing templates, routes, CSS, or controller code.
1. Inspect the path Wicked PDF actually resolves
Open a Rails console in the same environment as the failing application and run:
#1 Best Overall
WickedPdf.new.send(:find_wkhtmltopdf_binary_path)Interpret the result rather than assuming that a successful shell command on your own account proves Rails can run it.
- Empty or nil result: Wicked PDF found no candidate executable.
- A Bundler shim or unexpected wrapper: discovery is selecting a path that is not the intended binary.
- A real absolute path: continue with existence, permissions, and dependency checks.
Check the returned file from the host shell:
ls -l /absolute/path/to/wkhtmltopdf
file /absolute/path/to/wkhtmltopdf
command -v wkhtmltopdf
wkhtmltopdf --versionReplace the example path with the exact value returned by Rails. The application user—not only your login account—must be able to read and execute it.
2. Install a compatible wkhtmltopdf binary
Wicked PDF’s documented installation approach is to use the wkhtmltopdf-binary gem on Linux or macOS. Add it to the bundle used by the deployed environment, deploy, and verify the resulting executable from a Rails console. This is convenient when the gem’s packaged build matches the host operating system.
Alternatively, install a system package or a vendor build approved for your operating system. Whichever source you choose, record the version and path in your deployment documentation. A package upgrade can move the binary or change its library requirements, so do not rely on an implicit path that differs between releases.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
After installation, test a minimal conversion outside your application rendering code. For an HTML file:
Rank #2
wkhtmltopdf /path/to/simple.html /tmp/simple.pdfA successful command proves that the executable can start and create output. It does not yet prove that your Rails service account, production environment variables, or application assets are correct.
3. Set an explicit absolute path in Wicked PDF
When automatic discovery is unreliable, configure the real executable directly. In config/initializers/wicked_pdf.rb:
WickedPdf.configure do |config|
config.exe_path = '/usr/local/bin/wkhtmltopdf'
config.enable_local_file_access = true
endUse the path that exists on the target host; /usr/local/bin/wkhtmltopdf is an example, not a universal location. Restart the Rails application after changing an initializer. In a multi-stage deployment, ensure the path exists in every role that generates PDFs, including background-job workers.
An absolute path avoids differences between interactive shells, systemd, containers, cron, and process managers. It also prevents a Bundler shim or an unrelated executable earlier on PATH from being selected.
Some applications configure the object directly:
WickedPdf.config = { exe_path: '/usr/local/bin/wkhtmltopdf' }Use one configuration style consistently with the Wicked PDF version in your bundle, and do not leave conflicting initializers that overwrite one another.
4. Verify permissions and the service account
Find the user running Rails (for example, the user configured by your application server or job worker) and test as that user. The executable and each directory in its path must be traversable, and the file must have execute permission.
namei -l /usr/local/bin/wkhtmltopdf
sudo -u APP_USER /usr/local/bin/wkhtmltopdf --version
sudo -u APP_USER /usr/local/bin/wkhtmltopdf /path/to/simple.html /tmp/simple.pdfReplace APP_USER with the actual account. A binary that works as root or as your development user can still fail in production because of directory permissions, a restricted PATH, a read-only temporary directory, or a container policy.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →If the executable is inside a release directory, deployment cleanup may delete it while an older process still references it. Place system-managed binaries in a stable location or update the initializer and restart processes atomically during deployment.
5. Distinguish a missing binary from a missing system library
If the configured file does not exist or cannot be executed, fix the path and permissions. If the path is correct but the command exits with a dynamic-linker message such as libssl.so.1.1: cannot open shared object file, the executable is present but incompatible with the host runtime.
This second failure mode is an operating-system dependency mismatch. Install the library version required by that build, use a package built for the host distribution, or select another compatible wkhtmltopdf build. Do not try to solve a linker error by changing Rails routes or view templates.
Capture the exact stderr text and operating-system release when diagnosing this case. A container image may need the runtime libraries added explicitly even though the same binary works on a full virtual machine.
6. Test in layers before rendering a real view
- Resolver: print
WickedPdf.new.send(:find_wkhtmltopdf_binary_path)in the Rails console. - Filesystem: confirm the returned file exists and is executable.
- Identity: run
wkhtmltopdf --versionand a simple conversion as the Rails service account. - Configuration: set the absolute
exe_path, restart the application, and repeat the console check. - Application: render a minimal PDF action without custom assets or JavaScript.
- Assets: add your stylesheet, images, fonts, and JavaScript only after the minimal document succeeds.
This sequence tells you whether the failure occurs before wkhtmltopdf starts, while it starts, or while it loads your page.
7. Handle assets and local-file access after execution works
wkhtmltopdf runs outside the Rails application process. Relative URLs that work in a browser can fail during PDF generation because there is no browser session, host-relative base URL, or authenticated asset request unless you provide one.
- Use absolute, reachable URLs for stylesheets, images, fonts, and scripts, or use Wicked PDF’s asset helpers.
- Ensure production URLs use the correct scheme and host rather than development-only addresses.
- If the document reads local files, enable local-file access as shown in the initializer and verify filesystem permissions.
- Check that images and CSS are not blocked by authentication, a private network, or an expiring URL.
- Keep JavaScript-dependent rendering separate from binary troubleshooting; first prove that static HTML converts.
A successful binary test followed by a blank or unstyled PDF usually indicates asset URL, access, or page-loading behavior—not “location unknown.”
Common failures and precise fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Resolver returns empty | No executable discovered | Install wkhtmltopdf or the wkhtmltopdf-binary gem, then set an absolute exe_path. |
| Resolver returns a Bundler shim | Automatic discovery selected a wrapper | Point config.exe_path at the real executable and restart Rails. |
| “Permission denied” | Service account cannot execute or traverse the path | Correct ownership and mode; test with sudo -u APP_USER. |
| “No such file or directory” for a known file | Wrong path, deleted release, or missing interpreter/library | Check the path with ls/file; inspect linker errors and deployment cleanup. |
libssl.so.1.1 or similar error |
Host library mismatch | Install the required runtime or choose a compatible build. |
| Binary works manually, Rails still fails | Different user, environment, container, or PATH |
Run the command as the Rails account and configure an absolute path. |
| PDF is blank or missing CSS | External asset or local-file access issue | Use absolute URLs/Wicked PDF helpers and configure local-file access where needed. |
Deployment and reliability checklist
- Pin the binary source and version used by each environment.
- Install it in every web and worker image that creates PDFs.
- Set an absolute path in the initializer rather than depending on an interactive shell’s
PATH. - Run a post-deploy smoke test as the real service account.
- Keep temporary and output directories writable by that account.
- Log the resolved path, wkhtmltopdf version, exit status, and stderr without exposing document secrets.
- Retest after operating-system, OpenSSL, container-base, or package upgrades.
Or skip the browser setup
If your goal is a dependable screenshot or PDF of a public URL rather than Rails-specific HTML rendering, ScreenshotNeo provides a single HTTP request and an MCP server for AI agents such as Claude and Cursor. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFor a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for all options, including PNG/JPEG/PDF output, full-page and element capture, device and retina settings, custom CSS or JavaScript, waits, request blocking, headers, cookies, geolocation, caching, signed links, asynchronous jobs, bulk capture, and usage reporting.
Best Value
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)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}`);The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is included on every plan. Create a free ScreenshotNeo account.
FAQ
Should I set exe_path in an initializer or environment variable?
An initializer is the documented direct setting. If hosts differ, generate that setting from deployment configuration, but still resolve to an absolute path before Rails starts.
Can a valid path still produce “location unknown”?
Yes. The file may be non-executable, inaccessible to the service account, or unable to load a required shared library. Check permissions and the command’s stderr.
Recommended Free Tools
Why does a simple HTML file work while my Rails view fails?
The executable is then functioning; investigate asset URLs, authentication, local-file access, JavaScript timing, and page-loading behavior in the view.
Frequently Asked Questions
Should I set exe_path in an initializer or environment variable?
An initializer is the documented direct setting. If hosts differ, generate that setting from deployment configuration, but still resolve to an absolute path before Rails starts.
Can a valid path still produce “location unknown”?
Yes. The file may be non-executable, inaccessible to the service account, or unable to load a required shared library. Check permissions and the command’s stderr.
Why does a simple HTML file work while my Rails view fails?
The executable is then functioning; investigate asset URLs, authentication, local-file access, JavaScript timing, and page-loading behavior in the view.
The Bottom Line
Inspect Wicked PDF’s resolved executable first. Install a compatible wkhtmltopdf build, configure its absolute path, test it as the Rails service account, and treat linker errors and asset failures as separate problems.
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.
