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/world-110m.json

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, built for GDPR. Start your free trial or view a live demo.