Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallA “missing layout” in Wicked PDF usually means one of two different failures: the PDF is generated but has no CSS or images, or Rails raises ActionView::MissingTemplate before conversion starts. Treat them separately. Wicked PDF launches wkhtmltopdf as an external process, so that process cannot automatically use the asset context that makes the same page look correct in a browser. For an unstyled PDF, make every stylesheet, image, font and script reference resolvable by the renderer, then verify production assets and the renderer binary. For a true missing-template exception, fix the Rails template or layout lookup instead.
First, identify which problem you have
Look at the response and the generated file before changing configuration. The symptom determines the fix.
| Symptom | Likely area | First check |
|---|---|---|
| PDF is created but appears plain | Stylesheet path or asset availability | Inspect the generated stylesheet reference and make it an accessible URL/path or use a Wicked PDF helper. |
| HTML works in development but the production PDF loses assets | Asset-pipeline compilation or production URL/path | Confirm the PDF assets are precompiled and reachable from the machine running wkhtmltopdf. |
| Some images appear and others do not | One or more invalid image references | Validate every image path; remove or correct bad references and render again. |
Rails raises ActionView::MissingTemplate |
Template or layout lookup | Verify the requested template, layout, directory and format. |
| The renderer cannot be launched | wkhtmltopdf installation or executable path |
Confirm the binary exists in the deployment environment and configure exe_path when necessary. |
Do not apply CSS fixes to an ActionView::MissingTemplate exception. Conversely, changing a Rails layout name will not make an already-generated, unstyled PDF load CSS.
How Wicked PDF loads a page
Wicked PDF is a Rails wrapper around the wkhtmltopdf executable. The executable runs outside your Rails application. As the project maintainers put it, “The wkhtmltopdf binary is run outside of your Rails application; therefore, your normal layouts will not work.” Your browser may resolve a relative URL through the Rails server, development asset compilation and browser session, while the separate renderer may have none of those conditions.
Recommended Free Tools
#1 Best Overall
Think of the PDF input as a standalone HTML document. Every resource must be available to the process that converts it:
- CSS must be emitted as a URL or file path the renderer can read.
- Images must resolve individually; a single invalid image can affect other images in the output.
- Fonts, JavaScript and background assets need the same treatment.
- The deployment must contain the expected
wkhtmltopdfbinary and any required local-file access configuration.
Fix CSS and images in a PDF-specific layout
Use Wicked PDF asset helpers
In a layout used only for PDF responses, replace ordinary Rails asset tags with Wicked PDF helpers. A minimal layout might look like this:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<%= wicked_pdf_stylesheet_link_tag "pdf" %>
</head>
<body>
<%= yield %>
</body>
</html>Use the corresponding image helper for images in the view:
<%= wicked_pdf_image_tag("logo.png", alt: "Company logo") %>Wicked PDF also documents JavaScript helpers. Use them when a PDF view genuinely needs JavaScript, but remove unnecessary scripts first: rendering is more predictable when the document can be laid out from HTML and CSS alone.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use absolute references when the renderer can reach them
An alternative is an absolute HTTP(S) URL or an absolute filesystem path that is readable by the conversion process. The important test is not whether the URL works in your browser; it is whether the server process running wkhtmltopdf can resolve it in the same environment. A URL pointing at localhost, for example, may point to a different network namespace in a container or worker.
Inspect the rendered HTML or temporary input sent to wkhtmltopdf. Write down the final URL/path for each stylesheet and image, then request or open those resources from the renderer host. This catches incorrect relative paths, missing asset prefixes, hostnames that are unavailable inside a container, and URLs that require a browser session.
Precompile the assets used by PDF views
In an asset-pipeline application, explicitly precompile the CSS, images and other files referenced by PDF views. A page that works in development may be relying on on-demand compilation; production may expose only fingerprinted, precompiled files. Ensure the PDF stylesheet is included in the production asset configuration and that the deployed files match the names emitted in the HTML.
- Identify the PDF entry point, such as
pdf.cssorpdf.scss. - Add it to the assets that production precompiles if it is not already included.
- Deploy the resulting assets together with the Rails release.
- Open the final stylesheet URL from the machine that runs
wkhtmltopdf. - Repeat the check for every image, font and background URL used by the PDF.
Do not infer success from the normal HTML response. Compare the ordinary page and the PDF input in the same environment, after deployment, with the same host and asset configuration.
Check images independently
Validate each image reference rather than testing only the first logo. The project documentation notes an observed wkhtmltopdf behavior in which one missing image can prevent other images from appearing. Temporarily remove all images, render the PDF, then add them back in small groups. This isolates the offending path quickly.
- Check spelling, capitalization and fingerprinted filenames.
- Check that the image is served with a usable content type and without an authentication requirement the renderer cannot satisfy.
- Use
wicked_pdf_image_tagin PDF views where appropriate. - Retry after correcting or removing any invalid image, even if other image URLs look correct.
Resolve a real ActionView::MissingTemplate error
If Rails fails before a PDF is returned, inspect the exception’s requested path and formats. A missing layout is a lookup problem, not an asset problem.
- Confirm the template file exists in the expected view directory and has the format Rails requests, for example
.html.erbrather than a file available only as another format. - Confirm the layout name passed to the PDF render call exactly matches the layout file name. Check spelling, directory nesting and underscores.
- Confirm the controller action is rendering the intended template and not selecting a different format through content negotiation.
- If the PDF uses a dedicated layout, place that layout where Rails expects layouts and reference it explicitly rather than relying on an unrelated browser layout.
- Read the complete exception path after any Rails upgrade. An issue report about one upgrade is not proof of a universal fix; the requested template and your application’s render options are decisive.
Once Rails can render the HTML successfully, return to the asset checks if the resulting PDF is still unstyled.
Verify wkhtmltopdf and Wicked PDF configuration
The converter is an external dependency. Confirm it is installed in the same environment as the Rails process that creates PDFs, and confirm the executable is discoverable by that process. If it is installed in a nonstandard location, set Wicked PDF’s exe_path to the actual binary path. Check deployment logs for the exact command and renderer error.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Wicked PDF also exposes a local-file access setting. Whether to enable it depends on how your assets are delivered and on your security requirements. Do not switch it on blindly: first determine whether your PDF references local files, then restrict the files and deployment conditions as appropriate.
The project’s README lists Ruby 2.2–3.2 and Rails 4–7.0 as versions verified by that documentation. This is a historical compatibility statement, not a guarantee for every current Ruby, Rails, operating-system or binary combination. Record the exact gem version, Rails version, Ruby version and wkhtmltopdf build when diagnosing an environment-specific failure.
A repeatable diagnostic sequence
- Generate the PDF and classify the result: unstyled output, missing images, renderer-launch failure or
ActionView::MissingTemplate. - For a lookup exception, fix the template/layout path and format first.
- For a generated but plain PDF, inspect the final HTML sent to the converter.
- Test every stylesheet and image URL/path from the renderer’s host.
- Switch the PDF layout to Wicked PDF asset helpers or to absolute references that are demonstrably reachable.
- Precompile and deploy the PDF assets, then repeat the production check.
- Confirm the binary location and
exe_path; review renderer stderr and deployment logs. - Retest with one stylesheet and one image before restoring the full document.
Performance and reliability considerations
Keep PDF layouts small and deterministic. Each external request adds another possible timeout, DNS failure or authentication mismatch. Prefer a compact PDF stylesheet, stable asset URLs and images that the renderer can fetch without interactive browser state. If you must load remote resources, verify network access from the worker or container rather than from your workstation.
Separate failures in logging: record the requested Rails template/layout, the generated HTML resource URLs, the renderer executable path and the converter’s stderr. This makes a production-only asset problem distinguishable from a code deployment problem. A successful development render proves only that development’s server, assets and binary worked together.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsOr skip the browser setup
If your goal is a reliable screenshot or PDF of a web page rather than a Rails view rendered by Wicked PDF, ScreenshotNeo makes the capture in one request. It accepts the consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; 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.
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 service includes full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and margin controls, HTML/CSS-to-image, custom CSS and JavaScript, click and wait actions, request and resource blocking, custom headers/cookies/user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work to ease migration.
It also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account to get started.
Common errors and fixes
“CSS works in the browser but not in the PDF”
The browser and converter are resolving different contexts. Inspect the final stylesheet reference, use wicked_pdf_stylesheet_link_tag or an absolute reachable URL, and verify production precompilation.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →“The PDF has no images”
Check every image independently. One invalid reference can interfere with other images. Correct the path or use wicked_pdf_image_tag, then render again.
“MissingTemplate” after changing a layout
Rails cannot find the requested template/layout or format. Verify the exact name, directory, extension and render options before changing assets.
“No wkhtmltopdf executable found”
Install the binary in the deployment environment or set Wicked PDF’s exe_path to its actual location. Confirm the Rails process, not only your shell, can execute it.
“It fails only in production”
Compare production’s compiled assets, hostnames, filesystem paths, network access and binary versions with development. A development success does not establish production availability.
“Enabling local file access fixed it, but is that safe?”
Local-file access changes what the renderer can read. Decide based on your asset strategy and security boundaries, and enable only what your deployment requires.
Frequently Asked Questions
Does changing the Rails browser layout fix an unstyled Wicked PDF?
Usually no. The converter runs outside Rails’ ordinary browser asset context, so a PDF-specific layout with resolvable asset references is the relevant fix.
Should I enable local-file access for every Wicked PDF installation?
No. First determine whether your PDF actually uses local files, then evaluate the security implications for your deployment.
Is the README compatibility range a guarantee for current Rails releases?
No. Ruby 2.2–3.2 and Rails 4–7.0 are versions listed as verified in that documentation; test the exact gem, framework and binary versions you deploy.
The Bottom Line
Separate template lookup failures from asset-loading failures. Fix the Rails path for ActionView::MissingTemplate; for a plain PDF, make CSS and images reachable by the external wkhtmltopdf process, precompile them for production, and verify the executable and configuration in the deployment environment.
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.
