Reference
Troubleshooting
Diagnose access, rendering, downloads, storage and field-device problems.
On this page
Connection and authentication #
| Symptom | Action |
|---|---|
| 401 / 403 on map resources | Check key on the style AND its tile/font/sprite URLs; a header-only style request does not propagate a query key. Verify maps scope. |
| Pack estimate succeeds but download fails | packs authorizes POST; maps authorizes manifests and files. Grant both. |
| Certificate error | Use the right hostname and install the internal CA via your device-management process. Do not disable TLS validation. |
| Browser CORS failure | Inspect OPTIONS, allowed request headers and gateway CORS responses. Preserve Range and expose Content-Range/ETag. |
| Wrong gateway host/path in styles | Check forwarded proto/host/prefix or explicit base. baseUrl is the integration root, not /maps/. |
| 503 during authorization | Ask platform staff to check the authorization backend; database mode does not fall back to legacy key files. |
Start with GET /maps/v1/releases/current and a scoped key. Then request the individual service. A successful gateway /healthz alone does not establish that Photon/Valhalla are ready.
Blank maps and missing labels #
- Set container height; check WebGL availability and vendor CSS.
- Check map/style load ordering and re-add custom sources/layers on style.load.
- Inspect the first failed resource rather than repeatedly changing coordinates. A 200 HTML response is not a valid style JSON.
- PMTiles needs unchanged byte ranges. Do not gzip the archive or let a service worker cache a partial response as a complete file.
- Missing labels offline often mean fonts.tar was not extracted at the expected path or the fontstack directory was renamed.
- Missing symbols can indicate sprite JSON/PNG/@2x paths or a style/archive mismatch.
- At z15 outside shore boxes, use packProtocol for the verified GL JS parent fallback. Other errors may indicate corruption or unsupported sources.
Offline storage and stale data #
| Symptom | Action |
|---|---|
| QuotaExceededError | Estimate storage, allow extraction overhead, remove unused packs and retry; persistence requests may be refused. |
| Restart loses the offline map | Cache the app shell, retain ready pack records and ensure the service worker controls cold start. |
| Checksum mismatch | Delete/reset the affected partial file and download from the same manifest; never activate it. |
| Cached pack 404 | Server cache was evicted or release retired; rebuild/download a supported pack. |
| Old data | Display stored release/source date, compare current when connected and offer a verified replacement. |
| No offline address/route | Those services are not included; use local names or clearly saved route geometry. |
Expected local resource URLs should never silently fall back to public internet tiles or unrelated hosted fonts. Test once with every outbound request blocked.
GPS and data quality #
If location permission is refused, let the user change site/OS settings. A desktop without GPS may not locate when disconnected. A serial receiver requires a supported browser, device permission, matching baud rate and a valid satellite fix. Show last-fix timestamps and accuracy rather than implying every position is live.
An address may be missing because the source lacks it; a route may be absent because the road graph is disconnected; a depth can be estimated from satellite gravity. Report concrete coordinates, release ID, endpoint, status and a redacted error to platform staff. Omit API keys, session tokens and sensitive track data.