A blank or incomplete Google Map in a wkhtmltopdf PDF is not always a timing problem. The embedded browser may be rejected by Google, fail to run newer JavaScript, or be unable to download map tiles. Diagnose those possibilities separately: record your wkhtmltopdf build, inspect JavaScript errors and network failures, then decide whether a bounded wait is appropriate or whether a current browser renderer is required.
Start with a reproducible diagnosis
Before changing flags, capture the details that determine which class of failure you have:
- Run
wkhtmltopdf --versionand record the full output, including whether Qt is patched. - Record the operating system, input URL, Google Maps API mode, API-key restrictions, authentication requirements and the exact command used.
- Open the same URL in a current desktop browser and save a screenshot. Browser success proves that the page can work somewhere; it does not prove that wkhtmltopdf’s older engine can execute it.
- Save the PDF produced by wkhtmltopdf and note whether the map is blank, partly tiled, replaced by an error, or missing only after deployment.
The Google Maps JavaScript API browser-rejection message reported in a historical wkhtmltopdf issue was The Google Maps JavaScript API does not support this browser.
That report concerned wkhtmltopdf 0.12.5 and older after a Google browser-detection change in November 2018. It demonstrates a known compatibility failure, not a diagnosis for every blank map.
Turn on diagnostics before changing timing
Capture JavaScript errors
Run the conversion with JavaScript diagnostics and redirect standard error to a file:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated 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 match#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
wkhtmltopdf --debug-javascript https://example.com/map map.pdf 2>wkhtmltopdf-stderr.txtRead the file for browser-support errors, syntax errors, uncaught exceptions and failed script loads. The --debug-javascript option exposes messages from the embedded page; it does not add support for APIs that the engine lacks.
Verify JavaScript and images are enabled
wkhtmltopdf has settings for JavaScript and image loading. Make sure neither has been disabled globally or on the command line. A useful baseline is:
wkhtmltopdf --enable-javascript --images https://example.com/map map.pdfIf your build uses a configuration file or wrapper, inspect the generated command as well as the source code. A wrapper can silently add options such as --disable-javascript, --no-images or restrictive local-file settings.
Check the page outside the PDF process
Use browser developer tools to check the Console and Network panels. Look for Google Maps API-key errors, blocked requests, certificate failures, authentication redirects and tile requests that never complete. Compare the map’s container size before capture: a map initialized in a zero-height element can appear blank even when its scripts loaded correctly.
Free tools Windows power users keep installed
One-click scans. No signup required.
Decide whether this is a wait problem
What --javascript-delay actually does
--javascript-delay waits after page loading until the specified interval elapses, unless page JavaScript calls window.print(). It is a completion control, not a browser upgrade. Use it when the map is still performing asynchronous work after the initial load:
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
wkhtmltopdf --enable-javascript --javascript-delay 5000 https://example.com/map map.pdfChoose a bounded value based on your page’s normal load time and keep it consistent in production. A 2019 issue report found that increasing the delay did not repair one patched-Qt map failure, so a longer delay should not be treated as a universal fix.
Use --window-status for an explicit ready signal
If you control the page, set a status value only after the map and any overlays are ready:
<script>
// Call this after your map, markers and overlays finish loading.
window.status = 'maps-ready';
</script>Then wait for that value:
wkhtmltopdf --window-status maps-ready https://example.com/map map.pdfThis is more deterministic than guessing a delay, but it cannot help if the map script is rejected, throws an exception or cannot fetch its tiles. Add a timeout in your calling process so a missing status does not leave a worker waiting indefinitely.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Separate browser compatibility from tile and TLS failures
Compatibility symptoms
A browser-support message, syntax errors in modern JavaScript or failures in APIs unavailable to wkhtmltopdf point to the embedded engine. Google Maps can use client-side rendering features that old WebKit-based engines do not implement. Google documents raster maps as server-generated raster image tiles and vector maps as client-side WebGL rendering. For a JavaScript map attached to a normal div, raster is the default; the <gmp-map> element defaults to vector. If your page requires WebGL or newer language features, changing the wait time will not supply them.
Tile and image symptoms
A map with some streets or a partially filled grid can indicate that the JavaScript initialized but individual tile or image requests failed. A 2018 report for one wkhtmltopdf 0.12.5 setup recorded partial tiles and HTTPS image-load errors. Check outbound DNS, proxy rules, firewall egress, certificate trust and the URL schemes used by custom tile layers. Do not make HTTP a production workaround merely because one report said it worked in that environment; weakening transport security changes the risk profile and may fail elsewhere.
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
API keys, referrers and authentication
Confirm that the key permits the Maps JavaScript API and the APIs needed by your page. Referrer restrictions designed for a normal browser origin can reject a server-side PDF request. Conversely, removing restrictions can expose a key. Prefer a narrowly scoped server-side arrangement, pass required cookies or authorization headers through your rendering service, and verify that redirects do not lead to a login page inside the PDF worker.
Use an upgrade only as a controlled experiment
The official wkhtmltopdf downloads page lists 0.12.6 as the stable series and gives June 11, 2020 as its release date. Installing 0.12.6 may change behavior, but the available project history does not establish that it fixes Google Maps. Test the exact binary, patched-Qt build and operating-system package in a staging environment, then compare console output, tile completion and PDF layout. Do not represent an upgrade as a confirmed Maps solution without evidence from your own page.
Recommended Free Tools
When to move to a current browser renderer
If diagnostics show browser/API incompatibility or unsupported script features, move capture to a current browser automation renderer rather than accumulating flags. The wkhtmltopdf project status guidance specifically suggests Puppeteer (or wrappers) for sites using dynamic JavaScript. For reports whose HTML and CSS you control, it also names WeasyPrint and Prince as alternatives. These are project recommendations, not guarantees for a particular Google Maps page.
Migration checklist
- Render the page in a current Chromium-based environment and wait for a known map-ready condition.
- Allow the renderer’s network process to reach Google and any custom tile host over TLS.
- Recreate API-key, cookie, authorization, timezone and geolocation settings.
- Install the fonts used by labels and surrounding report content.
- Compare page size, margins, map scale, clipping and page breaks with the old PDF.
- Set a hard navigation and rendering timeout, collect console/network logs, and fail the job clearly rather than emitting a blank PDF.
Common failures and targeted fixes
Blank map with a browser-support message
Cause: Google rejected the embedded browser or the page uses features it cannot execute. Fix: verify the message with --debug-javascript, then test a current browser renderer. A user-agent override was proposed in a historical issue, but that report did not verify it as a solution; impersonation alone cannot add missing engine capabilities.
Blank map with no console error
Cause: JavaScript or images may be disabled, the map container may have no size, or a wrapper may suppress diagnostics. Fix: enable JavaScript and images, inspect computed container dimensions, and rerun with stderr captured.
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
Only some tiles appear
Cause: tile requests, certificates, DNS, proxy policy or rate limits may be failing independently of map initialization. Fix: inspect network failures from the PDF host, verify TLS trust and allow the required destinations. Check custom tile URLs separately from Google’s scripts.
More delay changes nothing
Cause: waiting cannot correct an unsupported engine or a request that will never succeed. Fix: stop increasing --javascript-delay; classify the error and move to compatibility or network remediation.
Works locally but fails in production
Cause: different binary builds, fonts, outbound access, proxy settings, API-key referrers, cookies or sandbox permissions. Fix: print the production version and command, compare environment variables and certificates, and capture stderr and network telemetry from the failing worker.
PDF completes before the map is ready
Cause: asynchronous map work outlasts the default capture point. Fix: add a bounded delay or implement a page-side ready status, then retain a timeout and verify that the status is actually reached.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability and cost considerations
A fixed delay increases every job’s latency, including fast pages. A ready signal can reduce unnecessary waiting but requires page cooperation. Browser automation generally consumes more memory than wkhtmltopdf, so size workers for concurrent pages and reuse a controlled browser process where appropriate. Cache stable map inputs only when the resulting imagery may legally and operationally be reused; live traffic, attribution and data freshness requirements can make caching unsuitable.
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 errorsBest 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
Keep a diagnostic mode that stores the command, renderer version, stderr, final URL and a failure classification. Retry transient network failures with a limit, but do not retry deterministic browser-support errors indefinitely. Treat blank pages, bot checks, timeouts and failed loads as distinct outcomes in your job metrics.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. One request can return a PNG, JPEG, WebP or PDF, with options for full-page capture, waiting, custom headers and cookies, JavaScript, viewport/device settings and PDF layout. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.
For a URL that renders correctly in a modern browser, the minimal cURL call is:
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 parameter details. The equivalent Python request is:
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}`);
const data = Buffer.from(await res.arrayBuffer());ScreenshotNeo also has an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. It includes 1,000 screenshots each month on the free plan with no card; paid plans start at $5 for 3,000 shots. Sign up free to try the capture before replacing your wkhtmltopdf worker.
A practical decision tree
- If JavaScript is disabled or images are blocked, correct those settings and rerun.
- If the console reports browser rejection or unsupported features, stop tuning delays and use a current browser renderer.
- If tiles fail, repair DNS, TLS, proxy, firewall, authentication or API-key access from the rendering host.
- If everything loads but capture is early, use a bounded delay or
--window-status. - If the page remains fragile after these checks, migrate the job and compare layout, fonts and operational cost in staging.
Frequently Asked Questions
Does wkhtmltopdf 0.12.6 guarantee that Google Maps will work?
No. It is the listed stable series, but the cited project history does not establish a Google Maps fix. Test your page and build.
Can a custom user agent bypass the Google Maps browser check?
It was suggested in a historical issue, but that report did not verify it. A user agent cannot add unsupported JavaScript or rendering features.
Should I switch map URLs from HTTPS to HTTP?
No as a general solution. One issue report described HTTPS failures in a specific setup; weakening transport security is not a safe universal workaround.
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 →Why does the map work in Chrome but not in a PDF?
Chrome and wkhtmltopdf use different browser engines. The page can be valid while the older embedded engine is rejected or unable to execute required features.
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.
