How to Fix wkhtmltopdf’s “xauth Command Not Found” Error with xvfb-run
Install xauth where xvfb-run runs, fix the service PATH, and verify the next error separately with this practical troubleshooting guide.
Direct answer: xvfb-run needs the xauth executable. When its lookup fails, it prints xvfb-run: error: xauth command not found and exits with status 3 before starting Xvfb or running wkhtmltopdf. Install the distribution package that provides xauth in the runtime that launches the command, then make sure that runtime can find it on PATH.
The important distinction is whether xauth is missing or merely invisible to the invoking process. A shell on the host, a PHP-FPM worker, a systemd service, a container, and a CI runner can all have different users, filesystems, and environment variables.
What the error means
The xvfb-run wrapper checks for xauth before it launches the virtual X server. It later calls xauth to create and remove X display authorization entries. If the executable lookup fails, the wrapper stops immediately with the literal message xauth command not found and status 3.
xauth is therefore an operating-system prerequisite for the wrapper. It is not a wkhtmltopdf input, command-line rendering option, or PDF setting. The wrapper source documents both the check and the authorization steps (xvfb-run implementation).
Step 1: Check the environment that actually runs xvfb-run
Run these commands as the same user and inside the same container, service, worker, or CI job that invokes wkhtmltopdf:
id
printf 'PATH=%s\n' "$PATH"
command -v xvfb-run || true
command -v xauth || true
xauth -V || true
A working command -v xauth in your administrator shell does not prove that the application process can see it. Record the output from the failing runtime, not from a different terminal.
Step 2: Install the xauth package in that runtime
Install the package named xauth (or the distribution package that provides the xauth executable) in the image or operating-system environment where xvfb-run executes. Use your platform’s package manager and repository policy; there is no single installation command that applies to every distribution.
For containers and CI, add the package installation to the image or job definition so a fresh environment receives it every time. Installing it only on a host does not help a container with its own filesystem.
After installation, verify the executable directly:
command -v xauth
ls -l "$(command -v xauth)"
xauth -V
If command -v still returns nothing, the package was installed in a different image, namespace, user environment, or filesystem than the one running the command.
Step 3: Fix PATH differences for services
If xauth exists but the application still reports it as missing, inspect the effective PATH of the service. Check the service user, environment cleanup rules, container entrypoint, and any process manager configuration. Configure the service to include the directory printed by dirname "$(command -v xauth)", then restart the worker.
XAUTH_PATH="$(command -v xauth)"
printf 'xauth=%s\n' "$XAUTH_PATH"
printf 'directory=%s\n' "$(dirname "$XAUTH_PATH")"
A PHP-FPM report describes the common pattern where the command succeeds in an interactive terminal but fails from PHP; community discussion points to differences in FPM’s environment and PATH. Treat that report as a diagnostic lead and verify your worker’s actual environment rather than assuming all processes share the shell configuration (wkhtmltopdf community issue discussions).
Step 4: Retry with a minimal rendering command
Once the same runtime can resolve xauth, retry a minimal command before adding application-specific flags:
command -v xauth
xvfb-run --server-args='-screen 0 1280x1024x24' \
wkhtmltopdf https://example.com /tmp/example.pdf
If this passes the xauth check but fails later, you have cleared the wrapper prerequisite. Diagnose the new message separately; fixing xauth does not guarantee that Xvfb starts, that wkhtmltopdf is present, or that the target page renders.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
xvfb-run: error: xauth command not found |
The executable is absent from the invoking runtime’s PATH. |
Install the package in that runtime, then run command -v xauth as the same user. |
| Works in a terminal, fails in PHP or a queue worker | The worker has a different user, PATH, container, or environment-cleaning policy. |
Print id and PATH from the worker, expose the directory containing xauth, and restart the worker. |
| Package appears installed but lookup is empty | Package was installed in another image, host, namespace, or filesystem. | Enter the exact container or execution environment and repeat the lookup there. |
| The xauth error disappears, then another error appears | The wrapper prerequisite is fixed; Xvfb, wkhtmltopdf, fonts, networking, or the URL may now be failing. | Capture the new stderr and troubleshoot that layer independently. |
| Intermittent failures in parallel jobs | Resource pressure, display collisions, or shared temporary directories can affect later stages. | Keep jobs isolated, monitor memory and temporary files, and inspect the first failing process in each job. |
Diagnostics checklist
- Run
idand printPATHin the failing process. - Run
command -v xauthandxauth -Vthere. - Confirm the package exists in the same container or host image.
- Confirm the service was restarted after environment changes.
- Retry a minimal
xvfb-runcommand. - Classify any subsequent error separately from the original missing-command failure.
Performance, reliability, and cost notes
Installing xauth adds a small operating-system dependency; it does not make page rendering faster. Rendering time is usually dominated by starting the browser stack, loading the URL, executing page JavaScript, and writing the PDF. Keep the package in a reproducible image, pin or review image updates through your normal process, and collect stderr and exit codes for failed jobs.
The fix has no special service fee: the cost is the package and the compute required to run your own renderer. If you run many workers, measure memory, CPU, temporary-disk usage, and queue time under your real concurrency. A successful xauth lookup is a prerequisite check, not a rendering benchmark or uptime guarantee.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server, so you can request a capture without installing wkhtmltopdf, Xvfb, or xauth. See the ScreenshotNeo API documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot.
- Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing result.
- An MCP server lets Claude, Cursor, and other MCP clients use
take_screenshot,get_page_info, andcapture_pdf. - Every plan includes the features; 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 to start with 1,000 screenshots per month and no card.
FAQ
Does installing wkhtmltopdf install xauth?
Not necessarily. xauth is a separate operating-system dependency used by xvfb-run; verify it with command -v xauth.
Can I fix this by passing a wkhtmltopdf flag?
No. The wrapper checks for xauth before invoking wkhtmltopdf, so a wkhtmltopdf rendering option cannot satisfy the prerequisite.
Why does the command work for root but not my application?
Root and the application may have different users, PATH values, containers, or service environment rules. Run the lookup as the application user in its actual runtime.
What should I do after the xauth error is gone?
Run the minimal test again and treat the next error independently. It may concern Xvfb startup, wkhtmltopdf availability, fonts, networking, or the target document.
Is there a universal package-install command?
No. Package names and commands vary by distribution and image. Use the package manager for your environment, then verify the executable in the process that launches xvfb-run.
