CARTO basemap tiles now show "API KEY REQUIRED" watermark on Geographic Distribution map (traefik-log-dashboard #229)

Traefik Plugins & Tools Traefik Log Dashboard
1

:octopus: GitHub issue traefik-log-dashboard #229, opened by matthabjan on GitHub

Description

CARTO changed their policy around 28 Aug 2026: anonymous (keyless) requests to their free basemap tile endpoints (basemaps.cartocdn.com) now return tiles stamped with a large “API KEY REQUIRED” watermark instead of clean tiles. This affects the “Geographic Distribution” map card on the dashboard, which pulls its basemap from CARTO without a key.

The underlying data (pins, total locations, total requests) still works fine. It’s purely a cosmetic/branding issue on the map tiles themselves.

Steps to reproduce

  1. Open the dashboard
  2. Go to the Geographic Distribution view
  3. Map tiles render with diagonal “API KEY REQUIRED Get your CARTO Basemaps API key | CARTO” watermarks over Europe, Africa, South America, etc.

Expected behavior
Clean basemap tiles with no watermark.

Suggested fix

CARTO now requires a free API key (no account needed, ~1 min signup at Get your CARTO Basemaps API key | CARTO) appended to tile requests as a query param, e.g.:

https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png?key=YOUR_KEY

Could you add an env var (e.g. PUBLIC_CARTO_API_KEY) that gets appended to the tile URL in the map component if set, similar to how other projects (Home Assistant cards) have patched this? Leaving it unset could keep the current behavior (watermarked but working) for backward compatibility.

Environment

  • Deployment: Docker Compose
  • Dashboard image: hhftechnology/traefik-log-dashboard:latest

:speech_balloon: Discuss it here. Status, fixes and code review stay on GitHub.

2

iconoclasthero commented on GitHub:

It looks like that’s here:
traefik-log-dashboard/dashboard/src/components/ui/map.tsx at 168f87ed6c962f7e49a8b4a4130c014946ec6489 · hhftechnology/traefik-log-dashboard · GitHub
and that it uses the raster maps.

Per Carto, they’re deprecating the raster maps in favor of vector maps:

We run two basemap services. Raster (PNG) is the older of the two and is being retired; vector is better on every axis that matters:

  • Sharper cartography — crisp at any zoom and on any display density, with no separate @​2x request.
  • Fresher data. We are considering stopping data updates to the raster basemaps, in which case that cartography stays where it is while vector keeps moving.
  • Restyleable in the browser — change colours, labels and layer visibility at runtime instead of baking them into a PNG.
  • Faster and cheaper to serve, which is a large part of how we can afford to keep the free allowance generous.

Your key covers both, so migrating later is one less thing to redo. The basemaps FAQ has a per-style migration table.

So it makes sense to also move to the vector maps while replacing the URLs to accept an API key.
CARTO Basemaps | CARTO Documentation
Example:

// Before — raster tiles in Leaflet
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY', {
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>, &copy; <a href="https://carto.com/attributions">CARTO</a>',
  subdomains: 'abcd', maxZoom: 20
}).addTo(map);

// After — vector style in MapLibre GL JS
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json?key=YOUR_KEY'
});
3

iconoclasthero commented on GitHub:

As I suspected, the conversion to vector is more than I’ve time to figure out right now…as is handling a new environmental variable.

A quick patch for v3.1.1 / main:

NB: This will hard-code your api key into a temporary, patched docker until an official update is released!

Enter your new CARTO_API_KEY:

CARTO_API_KEY=<your api key from email>
## verify:
printf '<your api key from email>="%s"\n' "$CARTO_API_KEY"

then

git clone https://github.com/hhftechnology/traefik-log-dashboard.git
cd traefik-log-dashboard
grep {y}.png dashboard/src/components/ui/map.tsx
## expected output:
#        "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png"
#        "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png"

If that’s not your output, you’ll have to figure it out from here, otherwise continue with

sed -i "s/{y}.png/{y}.png?key=$CARTO_API_KEY/" dashboard/src/components/ui/map.tsx
## verify with
grep {y}.png dashboard/src/components/ui/map.tsx
## expected output:
#        "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png?key=<your api key from email>"
#        "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png?key=<your api key from email>"

If all goes well, build the docker:

docker build -t traefik-log-dashboard:carto-key ./dashboard

And if that succeeds, modify docker-compose and restart…
cd to your docker/traefik-dashboard directory then:

sed -i 's|hhftechnology/traefik-log-dashboard:latest|traefik-log-dashboard:carto-key|' docker-compose.yml 
docker compose up -d --force-recreate traefik-log-dashboard

And, as the Carto page states:

If you still see the “API key required” watermark afterwards, force-refresh — your browser and our CDN both cache map tiles, so an old one can linger for a moment.

So do a Ctrl-F5:

Image
Image1582×446 52.2 KB

4

JeremyTBradshaw commented on GitHub:

Just curious if something is expected for official solution or if it’s worth signing up to Carto. I only see a free trial (30d), so am a little hesitant, figured I’d ask. Just got the dashboard up and running and like it a lot.

5

iconoclasthero commented on GitHub:

Just curious if something is expected for official solution or if it’s worth signing up to Carto. I only see a free trial (30d), so am a little hesitant, figured I’d ask. Just got the dashboard up and running and like it a lot.

Would you please show me where on Carto it says 30 days for personal use (<5M hits/mo)?
(It’s always that damn 5 million and first one that get’s ya!)

6

JeremyTBradshaw commented on GitHub:

Sorry I missed that there is an old and new version of Carto. But FYI for either if you are signing up, you end up here - https://auth.carto.com/u/signup and it says “Get started for free. With your trial account you can test drive CARTO for 30 days.”

But I have now see from the FAQ link above how there is the old version that is not planned to go away and will remain free. My bad. I’m happy to learn it’s free.

7

iconoclasthero commented on GitHub:

That signup URL didn’t work for me, but I did see elsewhere where it mentioned a 30-day free trial.
Regardless, just to clear this up for anyone else, sign up for a free, personal, up to 5 M uses per month api key at Get your CARTO Basemaps API key | CARTO
And, given the way this works, I don’t see how @​hhf could design this using their own API key (would share 5M uses/mo over all users of Traefik Log Dash) so I think you’ll need your own regardless of future development (assuming Carto remains the map vendor).

8

PHB-fra commented on GitHub:

Use openstreetmap like homeassistant ?