Mapbox GL JS v2.x tile cache persistence across token migration

Direct Answer

Cached tiles are not retained across token changes. Mapbox GL JS v2.x keys its IndexedDB tile cache by the full tile URL, which includes the access_token query parameter. When you call map.setAccessToken() or re-initialize with a new token, subsequent tile requests use the new token, producing new cache keys and cache misses. Tiles already resident in GPU memory or the browser's image cache continue to render until the viewport changes enough to request new tiles.

The library does not re-key or migrate existing IndexedDB entries. There is no public API to rewrite cache keys. The offline plugin (mapbox-gl-offline) stores regions in a separate database keyed by region definition, so previously downloaded offline regions remain accessible after a token change, but new downloads require the new token.

Confirmed Facts

• Tile cache keys in IndexedDB include access_token=OLD_TOKEN (verifiable in DevTools → Application → IndexedDB → mapbox-gl-js → tiles).
• map.setAccessToken('NEW_TOKEN') updates the token for future requests only; it does not rewrite existing cache entries.
• If your style URL embeds the token (mapbox://styles/...?access_token=...), setAccessToken() does not update it — you must call map.setStyle(), which clears the tile cache for that style.
• Browser storage quotas (IndexedDB, per origin) evict LRU entries under pressure, independent of token status.

Likely Behavior (Marked for Verification)

• Tiles already decoded in the current viewport show no immediate visual gap; placeholders appear only on pan/zoom that triggers new requests.
• Offline regions downloaded with a valid token at download time continue to render offline after token rotation, unless Mapbox enforces token validation on tile serving for private styles (rare for raster, common for vector tiles with private styles).
• No 401/403 occurs for tiles served from GPU/image cache; errors appear only on new network requests.

Recommended Migration Steps

1. Pre-fetch critical viewport tiles with the new token before switching: use map.getSource() and source.loadTile() (internal) or simply pan/zoom programmatically after setting the new token on a hidden map instance.
2. Switch token via map.setAccessToken(newToken) if your style URL does not embed the token. If it does, call map.setStyle(styleUrlWithNewToken) and accept a full style reload (clears current style's tile cache).
3. For offline-capable apps: ensure all required regions are downloaded before token rotation. After rotation, new region downloads use the new token automatically.
4. Monitor Network tab for 401 responses on tile requests post-migration; confirm no 401 for tiles already in view.

One Diagnostic Detail Needed

Does your style URL embed the access token (mapbox://styles/...?access_token=...) or do you rely solely on map.setAccessToken() / the accessToken constructor option? This determines whether a full setStyle() reload (and cache clear) is required.