The map is open, the vehicles have stopped moving, and the data is fine

Pick one vehicle that has stopped moving on the map and run a single query: the newest position row for that vehicle, ordered by server receipt time, not by device time. Compare that timestamp against the age the marker is showing. If the row is 20 seconds old and the marker says 14 minutes, the database has the data and something between it and the screen is not delivering it. That is the whole triage, and it takes a minute.

Do it in that order because the instinct is backwards. A frozen map looks like a data problem, so teams start with devices, SIMs and ingest queues — the slowest things to check and, in a fleet-wide freeze, the least likely. Transport and rendering fail more often, and they fail with no exception, no failed request and no alert. The screen simply stops changing.

The check that splits the system in half

1. Query the newest row for one frozen vehicle, and read the server receipt timestamp. Device time is not usable here: a device with a wrong clock will make a fresh row look ancient or a stale one look current.
2. Read the age the marker is displaying for the same vehicle. If your map does not display an age, stop and add one — you cannot run this comparison without it.
3. Check whether the freeze is fleet-wide or a subset. Every vehicle frozen at once points at transport or rendering. A handful frozen while the rest move is a different investigation entirely, covered in most of the fleet updating and 11 vehicles stale since morning.
4. Open the browser's network panel and look at the state of the live connection. An open socket with no messages for 3 minutes and a closed socket look identical on the map and have different repairs.
5. Reload the page. If everything jumps to current and then freezes again minutes later, you have confirmed a transport problem without touching the backend.

The causes, ranked by how often they turn out to be it

The socket that died quietly

A live map is usually one long-lived connection carrying position updates. Long-lived is the operative word: something between the browser and your server has an opinion about how long a connection may sit idle, and a reverse proxy or corporate firewall closing an idle connection after about a minute is ordinary.

Worse, the close is often not clean. A laptop lid closes, a phone hands over between cell and wifi, a network device drops the flow silently — and the browser learns nothing until it tries to send. The symptom is a connection that reports itself open, delivering no messages, forever.

• Send an application-level heartbeat every 20 to 30 seconds and expect one back. A transport-level keepalive you cannot observe is not a health check.
• Treat 2 missed heartbeats as a dead connection and tear it down deliberately. Waiting for the network stack to notice can take many minutes.
• Reconnect with exponential backoff and jitter, capped at about 30 seconds. Without jitter, a server restart brings every dispatcher's browser back simultaneously and the reconnect storm looks like a second outage.
• On reconnect, request a full snapshot of current positions before resuming the stream. This is the step most often skipped, and skipping it means the map stays wrong until every vehicle has independently pinged — several minutes on a parked-vehicle cadence.
• Show the connection state in the interface. A small "live" or "reconnecting" indicator turns an invisible failure into something a dispatcher reports in the first minute rather than the first hour.

A map that has silently stopped updating is worse than a map that is down. Nobody makes decisions from a blank screen; everybody makes decisions from a stale one.

Markers that get rebuilt instead of moved

The second-most common cause is a rendering pattern that is invisible at demo scale and fatal at fleet scale: on every update the map clears its markers and creates new ones. With 20 vehicles at a 30-second cadence nobody notices. With 400 vehicles reporting every 10 seconds, the browser is destroying and constructing 400 elements 40 times a minute, and the tab has no time left to paint.

The tell is that the whole page is sluggish rather than just the markers — scrolling stutters, buttons respond late, the fan spins. Three changes, in increasing order of effort.

1. Mutate rather than recreate. Keep a map of vehicle id to marker and update the position of the existing marker. This is usually a small change and often removes the problem entirely.
2. Coalesce updates to a fixed render rate. Buffer incoming positions and apply them 4 to 10 times a second rather than on arrival. Nobody can perceive a marker moving 40 times a second, and the browser is doing the work regardless.
3. Move to a canvas or WebGL layer and cluster above a few hundred markers in view. Individually styled elements stop being viable somewhere in the low hundreds, and the exact number depends on your marker complexity, so measure it on the oldest machine in the dispatch office rather than on a developer laptop.

The tab nobody is looking at

Browsers aggressively throttle background tabs to save battery. Timers that should fire every second are clamped to roughly once a minute, animation callbacks stop entirely, and a tab that has been in the background for a while may be frozen outright. A dispatch map left open behind a spreadsheet is not updating on any schedule you chose.

The repair is to stop trusting timers and start listening for the visibility change event: when the tab becomes visible again, request a fresh snapshot and re-establish the connection if it is not healthy. Pair that with the age display on every marker, so a dispatcher returning to a tab sees "3 minutes ago" rather than a position presented as current. It is the same honesty problem that makes arrival detection firing late or twice at a stop so expensive: a system that presents an old observation as a current fact will be believed.

Only now, the ingest path

If the newest row really is old, the investigation moves behind the database, in this order: consumer lag on the ingest queue, then the write path, then the devices. Queue lag is the one that produces a fleet-wide freeze with everything else healthy — messages are arriving and waiting, and nothing reports an error because nothing has failed.

• Consumer lag climbing steadily. Something downstream slowed — a slow write, an index rebuild, a scaled-down consumer group — and the backlog is the visible half of it.
• Write batching set too generously. A 60-second flush interval is efficient and makes every position on the map up to a minute old before any of this starts.
• A cadence policy doing exactly what it was told. Parked vehicles reporting every 15 minutes are not frozen, and the map should say so — which is the argument for setting ping cadence by what the vehicle is doing rather than one global interval.
• A noise filter dropping legitimate updates. Filters that suppress stationary jitter, of the kind discussed in the parked truck that keeps moving, can be tuned tightly enough to swallow slow movement in a yard.

The reconnect-and-resync discipline is not specific to maps. Any long-lived integration needs it, and the decision about how work arrives in the first place sets a floor on how fresh anything downstream can be — the trade-off in booking by carrier API or tendering over EDI. A batch channel that lands every 15 minutes cannot feed a screen that claims to be live, however good the map code is.

The decision tree, in one pass

1. Newest row fresh, marker stale, reload fixes it, and it recurs after minutes. Transport: heartbeat, backoff, snapshot on reconnect.
2. Newest row fresh, marker stale, reload fixes it and it does not recur. The tab was backgrounded. Resync on visibility change.
3. Newest row fresh, marker stale, reload does not fix it, tab at high CPU. Rendering: mutate markers, coalesce updates, cluster.
4. Newest row fresh, all markers stale, no socket open at all, and the server is healthy. Subscription or authentication failed silently on connect — check the server's view of active subscribers.
5. Newest row stale for every vehicle. Ingest: consumer lag, then write batching, then cadence.
6. Newest row stale for some vehicles only. Not this page. Go to the per-vehicle staleness investigation, which is an install, SIM and backfill problem.

Most of this is an afternoon of work done in advance: an age on every marker, a connection indicator, a heartbeat, a snapshot on reconnect. Building those in from the start rather than after the first frozen morning is the difference between a dispatch screen people trust and one they check by phone — the kind of thing we scope explicitly in MVP and product builds. Adjacent diagnoses sit in telematics and the live vehicle data plane, inside our logistics and mobility work.

• live map
• telematics
• frontend performance
• debugging