Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A longer wait is not a universal fix for a Google Map missing from a wkhtmltopdf PDF. First identify whether the map is still loading, whether Google or the map’s JavaScript rejects the embedded browser, or whether tile and image requests are failing. If the page relies on browser features wkhtmltopdf cannot support, use a current browser-based PDF renderer and verify the result in your own deployment.
Diagnose the failure before changing settings
Compare the PDF with the same page open in an ordinary browser, then gather the details needed to distinguish a timing problem from a renderer or network problem. A map working in a modern browser is useful evidence, but it does not prove the browser engine embedded in wkhtmltopdf can render it.
- Record the exact wkhtmltopdf version, build and patched-Qt details, operating system, and whether the input is a URL or a local HTML file.
- Note whether the map is entirely blank, partly rendered, or visible in the PDF but missing some tiles or labels.
- Check whether the same page displays in a normal browser in the same environment, especially if it depends on authentication, an API key, or network access.
- Keep a copy of the generated PDF and the full command and standard error output so you can compare changes one at a time.
These symptoms point to different causes: a map that appears after a delay may be asynchronous work; a browser-support error suggests compatibility; missing tiles with otherwise-rendered map content suggest resource or TLS failures.
Check JavaScript and browser compatibility
Google Maps is not a static image by default. Its JavaScript API runs in a browser context and requests map content. A historical wkhtmltopdf issue reported that, after a Google browser-support or detection change in November 2018, the Maps JavaScript API rejected wkhtmltopdf 0.12.5 and older with the message “The Google Maps JavaScript API does not support this browser.” That report documents one compatibility failure, not the cause of every blank map.
#1 Best Overall
- Bright, high-resolution 5” glass capacitive touchscreen display lets you easily view your route
- Get more situational awareness with alerts for school zones, speed changes, sharp curves and more
- View food, fuel and rest areas along your active route, and see upcoming cities and milestones
- View Tripadvisor traveler ratings for top-rated restaurants, hotels and attractions to help you make the most of road trips
- Directory of U.S. national parks simplifies navigation to entrances, visitor centers and landmarks within the parks
Enable JavaScript diagnostics and inspect standard error for script errors or a Google browser-support message:
wkhtmltopdf --debug-javascript https://example.com/map.html map.pdfReplace the example URL with your page. The settings reference exposes JavaScript and image-loading controls as well as JavaScript debug output. Check that JavaScript and images have not been disabled by command-line options or configuration. If diagnostics indicate unsupported browser behavior or script features, a delay will not make that engine compatible.
Use a wait only when the map is still loading
--javascript-delay is a wait control, not a compatibility switch. The setting waits after page load until the specified time elapses or JavaScript calls window.print(). It can help when the map is genuinely finishing asynchronous work, but it cannot add unsupported browser features or make Google accept an unsupported engine.
Rank #2
- 6” high-resolution navigator includes map updates of North America
- Hands-free calling when paired with your compatible smartphone with BLUETOOTH technology and convenient Garmin voice assist lets you ask for directions to places you want to go
- Road trip–ready features include the HISTORY database of notable sites, a U.S. national parks directory, Tripadvisor traveler ratings and millions of Foursquare POIs
- Driver alerts for things such as school zones, sharp curves and speed changes help encourage safer driving and increase situational awareness
- Access live traffic, fuel prices, parking, weather and smart notifications when you pair this navigator with your compatible smartphone running the Garmin Drive app
Try a bounded delay as a diagnostic, changing only the duration between runs:
wkhtmltopdf --javascript-delay 5000 https://example.com/map.html map.pdfThe value is milliseconds. If the output changes as the wait increases, timing may be involved; if it does not, do not keep increasing the delay indefinitely. A 2019 issue report describes a patched-Qt map failure that longer waiting did not fix.
The settings also document --window-status, which can wait for a page status value rather than an arbitrary fixed interval. Use it only if your page can reliably set that value after the map is ready. For example, page code you control could set window.status = 'map-ready' after its own readiness condition; then invoke wkhtmltopdf with the matching status. This is useful only when your page code can determine readiness accurately. A page that never sets the expected value can leave the conversion waiting rather than completing.
Rank #3
- Explore confidently with the reliable handheld GPS
- 2.2” sunlight-readable color display with 240 x 320 display pixels for improved readability
- Preloaded with Topo Active maps with routable roads and trails for cycling and hiking
- Support for GPS and GLONASS satellite systems allows for tracking in more challenging environments than GPS alone
- 8 GB of internal memory for map downloads plus a micro SD card slot
Investigate missing tiles, images, and network access
A map can render partially even when its scripts run: tiles and other images are separate requests. Inspect standard error for failed URLs, TLS errors, blocked resources, or connection timeouts. Confirm that the conversion host—not just your desktop browser—can reach the map and custom tile hosts, and that required credentials or API-key restrictions allow requests from that environment.
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 →A 2018 report for one wkhtmltopdf 0.12.5 configuration described partial map tiles and HTTPS image-load errors. The reporter said HTTP or a 0.13.0 alpha worked in that tested setup. This is a case-specific history, not a safe general fix. Do not weaken transport security by switching map resources to HTTP as a production workaround; determine which request fails and correct the underlying connectivity or certificate issue instead.
Understand raster and vector map behavior
Google documents two map rendering approaches: raster maps use server-generated raster image tiles, while vector maps use client-side WebGL rendering. For JavaScript maps attached to a div, raster is the default; the <gmp-map> element defaults to vector. This distinction can help explain why a page that relies on WebGL behaves differently from one displaying raster tiles, but changing map type is not an established general fix for wkhtmltopdf.
Rank #4
- 8” navigator with high-resolution, dual-orientation display and map updates of North America .Special Feature:Large Display; Voice Assist; Hands-Free Calling; Live Traffic and Weather; Traffic Cams and Parking; Smart Notifications,Driver Alerts; Tripadvisor; National Parks Directory; Find Places by Name; Garmin Real Directions Feature.
- Hands-free calling when paired with your compatible smartphone with BLUETOOTH technology and convenient Garmin voice assist lets you ask for directions to places you want to go
- Road trip–ready features include the HISTORY database of notable sites, a U.S. national parks directory, Tripadvisor traveler ratings and millions of Foursquare POIs
- Driver alerts for things such as school zones, sharp curves and speed changes help encourage safer driving and increase situational awareness
- Access live traffic, fuel prices, weather, parking and smart notifications when you pair this navigator with your compatible smartphone running the Garmin Drive app
If you control the map page, identify which map element and rendering mode it uses before testing a change. Validate any change in the final PDF renderer and environment; a result in a modern browser does not establish that wkhtmltopdf supports the same rendering path.
Check your wkhtmltopdf version, but do not assume an upgrade fixes Maps
The wkhtmltopdf downloads page lists 0.12.6 as the stable series and gives June 11, 2020 as its release date. That is useful version context, not evidence that upgrading to 0.12.6 resolves a Google Maps compatibility failure. Record the exact build you deploy and test it against the actual page, rather than treating a version change as a guaranteed repair.
When to move the PDF job to a current browser renderer
If logs show browser rejection or unsupported JavaScript behavior, or if a minimal test still fails despite successful resource access and a reasonable readiness wait, move the PDF capture to a current browser-based renderer. The wkhtmltopdf project status guidance says that for dynamic-JavaScript sites, consider Puppeteer or one of its wrappers; for report generation using HTML you control, it also names WeasyPrint or the commercial tool Prince. These are project recommendations, not a guarantee that a particular Google Maps page will work without adjustments.
Best Value
- Bright, high-resolution 5” glass capacitive touchscreen display lets you easily view your route
- Get more situational awareness with alerts for school zones, speed changes, sharp curves and more
- View food, fuel and rest areas along your active route, and see upcoming cities and milestones
- View Tripadvisor traveler ratings for top-rated restaurants, hotels and attractions to help you make the most of road trips
- Directory of U.S. national parks simplifies navigation to entrances, visitor centers and landmarks within the parks
Before switching, validate the things that affect the real output:
- Whether the renderer’s browser is accepted by the Maps API and supports the page’s JavaScript and rendering features.
- Whether the conversion environment can load map tiles and other external resources over TLS.
- Whether the page’s API-key restrictions, authentication, headers, or referrer rules work from that environment.
- Whether the map is ready before PDF capture and whether the output preserves fonts, dimensions, pagination, and layout.
- Operational constraints, including the runtime and cost of running the chosen renderer in your deployment.
Choose based on the failed layer. A new renderer addresses browser capability; it will not automatically correct an invalid key, blocked request, or page-specific readiness issue.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need to capture a page without maintaining your own browser-rendering setup, ScreenshotNeo is a website screenshot API and MCP server. Its API can return PNG, JPEG, WebP, or PDF output. It is an alternative capture path, not a promise that every Google Maps page, API-key configuration, or layout will render identically; validate your page and output format.
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 problemsFor an image capture, the one-call example is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/map.html -o map.webpSee the ScreenshotNeo API documentation for request options, including PDF capture. Cookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the page verdict and billing status. An MCP server provides screenshot tools for AI agents, and the free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Sign up for the free plan.
Common errors and what to try
| Symptom | Likely layer | Next step |
|---|---|---|
| “The Google Maps JavaScript API does not support this browser.” | Browser/API compatibility | Inspect JavaScript diagnostics and test with a current browser-based renderer. A user-agent override was proposed in an issue discussion but was not verified there as a solution. |
| Map appears partly, with missing tiles | Image or tile requests, connectivity, or TLS | Inspect failed resource requests and confirm the conversion environment can reach them securely. |
| Blank map with no obvious error | Could be timing, script compatibility, blocked requests, or page configuration | Compare browser output, inspect debug output, verify JavaScript and image loading, and follow the evidence rather than assuming a longer delay is enough. |
| Map never finishes when using a status wait | Expected readiness status was not set or did not match | Confirm your page sets the exact status string after its readiness condition, or use a bounded delay as a diagnostic. |
| Map works locally but not on the conversion server | Environment-specific network, credential, or key restriction | Check server-side access, authentication, API-key/referrer rules, and TLS for map and custom tile requests. |
Practical decision path
- Record the wkhtmltopdf version, build, operating system, command, and page URL; compare the PDF with the page in a regular browser.
- Run with
--debug-javascript; verify JavaScript and image loading are enabled. - If the map is simply completing asynchronous work, try a bounded
--javascript-delayor a status wait your page explicitly sets. - If resources fail, fix reachability, TLS, or credentials for the failed requests; do not treat HTTP as a general workaround.
- If browser/API compatibility or unsupported features are implicated, validate the page in a current browser-based PDF renderer and check its output and deployment constraints.
Frequently Asked Questions
Does wkhtmltopdf 0.12.6 definitely fix Google Maps?
No. The available version information identifies 0.12.6 as the stable series, but does not establish it as a Maps compatibility fix.
Can I use a browser user-agent string to make Google Maps work?
An issue reporter proposed browser impersonation, but the report does not verify it as a working remedy. Diagnose the engine and script errors before relying on that approach.
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.
