Skip to content

Visitor Map — troubleshooting

This page covers issues unique to the Visitor Map (mw.js). Most widget failures are environment-related — see common troubleshooting first.

The Map shares its dependency chain with the 3D Globe — D3.js, TopoJSON, and the same world atlas. If the Map fails to load, the Globe almost certainly fails the same way.

The Map has two display modes:

  • heatmap (default) — countries shaded by visit share. Calls statable.com/api/widget/countries.
  • cities — dots at visitor coordinates. Calls statable.com/api/widget/points.

Switch via data-display-mode. Most "Map shows nothing" reports are not bugs — they're new sites with no traffic yet.

"Failed to load script" or world atlas fetch failure

Same root causes as the Globe — see Globe troubleshooting. The Map needs:

  • D3.js from https://d3js.org
  • TopoJSON from https://unpkg.com
  • world-110m.json from https://statable.com/maps/

All three must be reachable. The most common blockers are ad-blockers, privacy extensions, corporate firewalls, and missing CSP entries — see common troubleshooting.

"API response does not contain a valid 'points' array"

Fires only when data-display-mode="cities" is set. The default heatmap mode doesn't check for a points array and never throws this.

Widget initialization error: Error: API response does not contain a valid 'points' array.

Most common reason: a new site without enough traffic for city-level aggregation. Switch to the default heatmap mode — it works at any traffic volume.

If you're not setting data-display-mode at all, this error is impossible.

Map renders, but every country is grey

In heatmap mode, countries with no visits are filled in grey by design (hsl(0, 0%, 92%) in light, hsl(0, 0%, 25%) in dark). If every country is grey, the API returned {} — your site has zero recorded visits in the data-period window.

Verification:

  • Confirm the tracking script is installed on the site whose hash you're using.
  • Open a few pages on the site, wait a couple of minutes, then refresh the widget.
  • data-period defaults to 7d. If you set it to a short range on a low-traffic site, expect a mostly-grey map.

Map is empty or fully one colour

If the widget reports no error but the map area looks blank or solid-coloured:

  1. Open DevTools → Elements and find the widget's <svg> inside the container.
  2. If the <svg> exists with <path> children, the data is being drawn — your page CSS is overriding fill or stroke. Global rules like svg path { fill: transparent } cascade into the widget.
  3. If the <svg> has no <path> children, the world atlas didn't parse — usually because a custom proxy returned an HTML error page where the JSON was expected. Restore the default world-110m.json source.

Tooltip is blank when hovering over countries

The tooltip uses inline DOM nodes inside the widget container — no external library. If you see a tooltip frame with no text:

  • Your page CSS has a global rule like * { color: transparent } or body * { font-size: 0 } cascading into the widget.
  • A print stylesheet or accessibility override is applied to all <div> content.

Scope your global rules so they don't cascade into widget-internal elements.

Map is much smaller or larger than the container

The Map defaults to 640 × 320 px (2:1 aspect, matching the Natural Earth projection). Without explicit data-width / data-height, the SVG renders at that size — inside a smaller container it clips, inside a larger container it leaves padding.

Set data-width and data-height on the snippet to your actual container size. Keep the aspect close to 2:1 to avoid empty bands above and below the map.

Ready to take control of your web analytics? Try Statable free for 30 days — no credit card required, full feature access, GDPR-compliant by default. Start your free trial or view a live demo.