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 →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The QStandardPaths: XDG_RUNTIME_DIR not set message usually means Qt could not find a private runtime directory for the user running wkhtmltopdf. By itself, it is a warning—not proof that PDF generation failed. In an interactive session, use the session manager’s existing directory; for a headless service, give the service account a private, mode-0700 directory. If conversion still fails, troubleshoot Qt’s display backend separately.
What the warning means—and whether it is safe to ignore
XDG_RUNTIME_DIR identifies a per-user directory for runtime files and sockets. The XDG Base Directory Specification says that when the variable is unset, an application should use a suitable replacement and print a warning. Qt may therefore report a fallback such as /tmp/runtime-user. That message tells you the variable was unavailable; it does not, on its own, say that the HTML could not be rendered or that the PDF is invalid.
Check the command’s exit status and the output file before treating the warning as a conversion failure. If the process exits successfully and the PDF opens and contains the expected pages, the warning may be harmless for that run. It is still better to configure a correctly owned runtime directory, particularly for a service or a multi-user machine, rather than relying on an unspecified fallback.
A runtime directory should be owned by the user running the process, inaccessible to other users (mode 0700), on a local filesystem, and associated with that user’s login or service lifetime. Do not point multiple users at one shared directory.
#1 Best Overall
Fix it in an interactive login session
First check whether your login or session manager already provided the variable. Prefer that directory over creating a new one. The following Bash-compatible commands use /run/user/UID only if the variable is empty, and then verify the directory’s owner and permissions before conversion:
printf 'XDG_RUNTIME_DIR=%sn' "${XDG_RUNTIME_DIR-}"
if [ -z "${XDG_RUNTIME_DIR-}" ]; then
candidate="/run/user/$(id -u)"
if [ -d "$candidate" ] && [ "$(stat -c '%u' "$candidate")" = "$(id -u)" ]; then
export XDG_RUNTIME_DIR="$candidate"
else
printf 'No owned session runtime directory at %sn' "$candidate" >&2
exit 1
fi
fi
stat -c '%U %a %n' "$XDG_RUNTIME_DIR"
wkhtmltopdf input.html output.pdf The stat output should show the invoking user as owner and 700 as the mode. If a session manager supplied a different path, verify that path instead of overriding it. If the expected directory does not exist or belongs to another user, do not create a shared substitute under /run/user; use the headless-service approach only if this is actually a service without a managed login session.
Set up a headless service or cron job
A cron task, container, or background service may not inherit a desktop login environment. Create a private directory for the account that runs wkhtmltopdf, export it in that process’s environment, and remove it as part of the service lifecycle. The example below assumes an administrator creates the directory and that the service runs as the account named wkhtml:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
RUNTIME_DIR=/tmp/wkhtmltopdf-runtime
SERVICE_USER=wkhtml
install -d -m 700 -o "$SERVICE_USER" "$RUNTIME_DIR"
# Run these commands as the service account, or set them in its environment:
export XDG_RUNTIME_DIR="$RUNTIME_DIR"
export QT_QPA_PLATFORM=offscreen
wkhtmltopdf input.html output.pdfReplace wkhtml with the real service account. The install command generally requires administrator privileges to assign ownership to another user; do not run the conversion itself as root just to create the directory. Verify the resulting owner and mode as the service user. Ensure cleanup follows the service’s lifecycle so a temporary runtime directory is not left indefinitely. For a short-lived job running as its own unprivileged account, a private temporary directory created by that account can also be used, provided it remains available for the entire conversion and is removed afterward.
Keep the environment settings with the process that actually launches wkhtmltopdf. Setting XDG_RUNTIME_DIR in an interactive terminal will not automatically fix a separately launched cron job or service; confirm the variable from that job’s own environment.
Separate the XDG warning from Qt graphics errors
Setting XDG_RUNTIME_DIR addresses the runtime-directory warning. It does not select a working graphics backend, make a display server available, or repair an incompatible Qt build. If the log also contains messages such as failed to get the current screen resources, QXcbConnection, or QPainter::begin(): Returned false, investigate those as separate rendering errors.
Headless rendering
For a headless Unix process, try QT_QPA_PLATFORM=offscreen in the same environment as the conversion, as in the service example. The wkhtmltopdf Unix Qt 5 initialization sets this value before constructing QApplication, but does not overwrite an existing value. Thus, an inherited setting such as xcb can remain in effect. Print the variable to see what the process is actually using.
Desktop or remote-display rendering
Qt documents xcb and wayland as platform choices through QT_QPA_PLATFORM. Use a display-backed platform only when the corresponding display and Qt support are available to the process. Check the environment’s display variables and installed Qt build; a desktop session’s display may not be accessible to a cron job, container, or service account. Do not keep changing the XDG directory to solve an error that points to display resources or painting.
Verify the environment and the actual PDF
Use this checklist in the same shell or service context that runs the conversion. It helps distinguish a missing runtime directory from an unrelated rendering problem:
- Identify the binary. Run
wkhtmltopdf --versionand record the exact output. Distribution packages may differ, so do not assume every installed build behaves identically. - Print the relevant environment. Run
printf 'XDG_RUNTIME_DIR=%snQT_QPA_PLATFORM=%snDISPLAY=%snWAYLAND_DISPLAY=%sn' "${XDG_RUNTIME_DIR-}" "${QT_QPA_PLATFORM-}" "${DISPLAY-}" "${WAYLAND_DISPLAY-}". An empty value is useful diagnostic information, not a command to copy blindly into another user’s environment. - Check the directory. Confirm it exists, is local, is owned by the process user, and has mode
0700. For example,stat -c '%U %a %n' "$XDG_RUNTIME_DIR"works on GNU/Linux systems with GNUstat. - Try a minimal conversion. Run
wkhtmltopdf input.html output.pdfwith a simple local HTML file, then inspect both the exit status and the resulting PDF. A warning disappearing is not enough if the output is still missing or malformed. - Classify any remaining error. If the warning is gone but conversion fails, use the other log messages to investigate Qt, the display backend, input accessibility, or the installed build rather than changing the runtime directory again.
Troubleshooting common outcomes
| Symptom | Likely explanation | What to do |
|---|---|---|
| The warning appears, but the PDF is created and opens correctly. | The process used a fallback runtime directory; the warning alone did not prevent this conversion. | For repeatable service runs, configure a private runtime directory with the right owner and permissions. Check the exit status and PDF rather than using the warning as the only success test. |
| The warning remains after setting the variable. | The variable may not reach the process, may be empty in that launch context, or may point to a directory that is unavailable to the service user. | Print XDG_RUNTIME_DIR from the same job, then verify the path exists and has the required owner and mode. Set it in the launcher or service environment that invokes the binary. |
| The warning disappears, but the command still fails with screen-resource or QXcb errors. | The runtime directory was not the cause of the separate display/backend failure. | Check QT_QPA_PLATFORM, display availability, and whether the installed Qt build supports the selected platform. For headless rendering, test offscreen. |
| The directory is rejected, shared, or owned by another account. | Runtime directories are per-user and private; a common directory for multiple service accounts violates that model. | Create a separate mode-0700 directory owned by each account and arrange cleanup with its service lifecycle. |
| The minimal local test works, but the real document does not. | The runtime warning is less likely to explain the difference; the input or its rendering dependencies may be involved. | Compare the actual process environment and test document with the failing job. Keep the investigation focused on the specific error output; do not assume the XDG fix resolves every wkhtmltopdf failure. |
Version and input-safety context
The wkhtmltopdf project page lists the 0.12.6 stable series as released on June 11, 2020. That date describes the project’s listed stable series, not necessarily the version installed by your operating system’s package manager. Use wkhtmltopdf --version to identify the binary you are troubleshooting.
The project warns against using wkhtmltopdf with untrusted HTML because unsanitized input can enable complete server takeover. Fixing a runtime-directory warning does not make untrusted HTML safe. If a service accepts user-supplied markup or URLs, treat that as a separate security boundary and do not expose the converter to untrusted input without an appropriate isolation and sanitization strategy.
Free tools Windows power users keep installed
One-click scans. No signup required.
Or skip the browser setup
If your goal is a website screenshot rather than a locally rendered wkhtmltopdf PDF, ScreenshotNeo provides a one-request screenshot API. It is not a fix for wkhtmltopdf’s Qt warning and does not replace the local conversion workflow when that is what you need.
For example, this cURL request saves a screenshot of Stripe as a WebP file. See the ScreenshotNeo API documentation for request options:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the page verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to AI agents using Claude, Cursor, or another MCP client. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
FAQ
Does changing XDG_RUNTIME_DIR change what appears in the PDF?
No. It configures a runtime location for the process; it is not a page-content or PDF-layout setting.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Should I add the variable to my shell profile?
Only if that is the environment that launches the converter and the chosen directory exists with the right ownership and permissions for that user. A cron task or service needs the setting in its own launch 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.
