OpenStreetMap is blocking use of their tile servers whenever Referrer is not included

Describe the bug
OpenStreetMap is blocking use of their tile servers whenever Referrer is not included. This is a change in the last few days. See https://wiki.openstreetmap.org/wiki/Blocked_tiles.

To Reproduce

Use folium.Map in any way with the default OSM tiles as the map.

Remaining to be understood
Can you send a Referrer header when running in an embedded way say in a Jupyter Notebook? How could their policy be satisfied when it's running locally or just being viewed in a notebook / potentially even a VS Code Notebook that doesn't have a URL (not Jupyter in a browser but Jupyter in an app).

Hi Peter,

I was unable to reproduce the issue. Do you also have this issue when you open our documentation? https://python-visualization.github.io/folium/latest/index.html should contain some maps that use the OpenStreetMap base tiles.

Hi Hans,

It's only happening for me in two situations. Also this only started a few days ago when they implemented the policy change at OSM.

Situation 1:

m = folium.Map(location=[lat,lng], zoom_start=11)
m.save("smoothed_overlay.html")

Then open up the html file in a browser such that the browser is reading the local filesystem directly / no hosting / not localhost in the location bar. In this case most all browsers will not send referrer information.

Situation 2:
If I create a map in VS Code's notebook app and then run display(m) it will also not have any referrer information. I think it might work in Jupyter Notebook (although I don't ever use that) because Jupyter runs in the browser and may will then send a localhost-like referrer.

-Peter

Ah I see. That's annoying. We cannot add these headers from Folium, they are added by the browser (or any other html renderer). The best advice I can give for now is to use a different tile provider. Maybe you can host your own?

Yeah I figured as much. Mostly wanted to give you a heads up in case there's another open tile provider you want to switch to by default for the purpose of ensuring broad compatibility out of the box instead of each developer having to figure out an API key if they happen to be working in an environment like VS Code Jupyter that requires it.

I'm facing the same issue currently

I am also facing the issue

Ah I see. That's annoying. We cannot add these headers from Folium, they are added by the browser (or any other html renderer). The best advice I can give for now is to use a different tile provider. Maybe you can host your own?

Looking at https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/referrerPolicy, it looks like you can set a referrerpolicy attribute on the <img> element?

There is also this PR Leaflet/Leaflet#9883, it seems like it may solve this?

@Julianiolo

@Julianiolo Not sure if the upstream PR will solve this particular issue. That PR is for sites where on site level the referrer header is blocked or otherwise not setup correctly for OSM. What people have reported in this thread is issues with OSM when there is no site where the map is served from (the map is rendered from a file or from inside VSCode). In that case there really is no valid referrer value, whatever the referrerPolicy is that is set on the image.

I am afraid we are out of luck. OSM requires a referrer header which should give the URL where the original map is served from (so they can track who is using OSM). For local files or use within VSCode there is no such URL, so the browser does not send it.

I have successfully reproduced the 403r Access Blocked error in a local file:// environment and confirmed a working fix. While the browser defaults to a strict referrer policy for local files, leaflets TileLayer already supports a referrerPolicy option that satisfies OSM's new requirements.

A fix is by injecting "referrerPolicy: "no-referrer-when-downgrade"into theL.tileLayer` options, the browser is instructed to send the local file path as the referrer header. I verified that this immediately clears the 403 block on local browsers.

Proposed JS fix
Folium could resolve this by adding a referrerPolicy argument to the TileLayer and Map classes to pass this string to the leaflet template.

// Verified working JS fix:
var tile_layer = L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", { "referrerPolicy": "no-referrer-when-downgrade", // ... other options }).addTo(map);

I have a minimal reproduction of the html with the fix, if any one wants to inspect it further.

@reory

i tried @reory solution and it worked when i set referer policy as strict origin
to generate a folium map in VSCode and save it to HTML

this works for my case in generating a small geographical scope (county-level)
haven't really tested for much wider coverage

import folium as fl

map = fl.Map(location=[_x_, _y_],
                tiles=None,
                zoom_start=7)
fl.TileLayer(
    tiles="https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    attr="&copy; <a href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
    referrer_policy="strict-origin",
).add_to(map)

map.save("test_layer.html")

@pprianto

I'd tried @pprianto , however it doesn't work for my case.
So I have a quick fix for anyone working with Folium on a web app. Just add a js script to find the map object, inject the header, and redraw.

<script>
  // fix OSM map referrer policy
  var _osmFixInterval = setInterval(function() {
    var iframes = document.querySelectorAll('iframe');
    for (var i = 0; i < iframes.length; i++) {
      try {
        var win = iframes[i].contentWindow;
        var mapKey = Object.keys(win).find(function(key) {
          try {
            var val = win[key];
            return val && typeof val === 'object' && typeof val.eachLayer === 'function';
          } catch(e) { return false; }
        });
        if (mapKey) {
          clearInterval(_osmFixInterval);
          win[mapKey].eachLayer(function(layer) {
            if (layer instanceof win.L.TileLayer) {
              layer.options.referrerPolicy = 'strict-origin';
              layer.redraw();
            }
          });
          break;
        }
      } catch(e) {}
    }
  }, 300);
</script>

@hansthen

@hansthen Is this bug now fixed please? Do you need any assistance to fix this?

Is there any planned update for the folium.TileLayer function to solve this issue?

I am also facing the issue.

It looks like there is no way to provide a valid HTTP Referer from within a Jupyter Notebook and the OSM usage guidelines explicitly forbid using strict-origin as a policy to avoid sending a Referer.

A somewhat drastic fix for this could be to change the default tile provider to something else like CartoDB Positron. I like the design of CartoDB, but what is your opinion on this?

A change of default tile provider would probably still only be a temporary solution. It is very likely that other thile providers will at some point earlier or later also enforce this.
The OSMF tile usage policy stated the requirement for sending a valid http refer since I think at least about 10 years. So it was actually never supposed to work, only now it is enforced.
https://operations.osmfoundation.org/policies/tiles/

But I think this could maybe be fixed by injecting a static header: 'X-Requested-With' at the appropriate place when creating the leaflet map object.
See discussion on OSM Forum
https://community.openstreetmap.org/t/error-403-when-using-local-files-referer-missing-can-i-use-user-agent-and-what-should-it-contain/142447/46

I don't see how we can solve this inside Folium. This looks like an OSM design decision that has consequences for all users. If this could be solved it should be solved upstream.

Changing tiles to CartoDB positron for folium maps to fiw a recent is…

Update

Ignore what I said below. The plugin URL is wrong, but there's also a potential issue with the OSM tile server itself that prevents this from working -- see clarisma/libgeodesk#37.

We've encountered the same issue in GeoDesk.

Local HTML files opened via file:// by definition don't have a Referer header, and hence can't comply with the OpenStreetMap's Tile Usage policy requiring referers.

As an alternative, tile requests may set an X-Requested-With header (I confirmed this with the OSM Operations Working Group).

You'll need to include the leaflet-header plugin and set the header as part of the tile layer.

As an example, for GeoDesk's GOL Tool, this looks as follows:

<script src="https://unpkg.com/leaflet@1.8.0/dist/leaflet.js"></script>
<script src="https://unpkg.com/leaflet-header/index.js"></script><style>

var tileLayer = new L.TileLayer(tilesUrl, {minZoom: 0, maxZoom: 19, attribution: tilesAttrib},[{header: 'X-Requested-With', value: 'geodesk-gol/2.3.6'}], null);

(Change geodesk-gol/2.3.6 to the Folium-specific identifier).

Hi,
There is a working leaflet example solving this issue https://community.openstreetmap.org/t/error-403-referer-missing-when-missing-on-local-files-when-using-firefox-but-not-chromium/147499/25

Is an integration in folium possible ? Maybe as an option and with a mandatory parameter for the application name ?

I'm using folium to make maps in html and send the files to people that are not going to run a webserver, so it would be very nice if I can continue doing that with OSM tiles (best looking tiles that requires no API key)

@junelac

@junelac Thanks for the request. I just now also properly read the solution described by @clarisma. I will reopen the issue and try to implement a fix the coming days.

@junelac

@junelac and @clarisma on second reading, this will also not work for folium. The plugin mentioned only works for WMS tiles. However, there is a fix you can implement in user space.

create_tile = folium.JsCode("""
    function(coords, done) {
        const url = this.getTileUrl(coords);
        const img = document.createElement('img');
        fetch(url, {
          headers: {
            "X-Requested-With": "<whatever>"
          },
        })
        .then((response) => {
            img.src = URL.createObjectURL(response.body);
            done(null, img);
        })
        return img;
    }
""")

folium.TileLayer.include(create_tile=create_tile)
tiles = folium.TileLayer(
    tiles="OpenStreetMap",
)
m = folium.Map(
    tiles=tiles,
)

@hansthen

Thank you @hansthen. If the fix cannot be added to folium maybe it can be added to the online doc ? I think my use case is not rare, and it would be better to find the solution in the doc than having to scour issues and forums

Let me think about it a bit how to add this to folium. In general I'd like to keep the API as simple as possible.

One probably would not always want to add X-Requested-With to the TileLayer requests, so it has to be configurable somehow. But also there are several TileLayers (like the one for WMS as well).

Perhaps you have a suggestion how we can add this cleanly to the API?

Thanks again ! Unfortunately it's outside my domain of competence, so I can't really give you a good advice on how to implement a solution

Navigation Menu

Repository navigation

OpenStreetMap is blocking use of their tile servers whenever Referrer is not included #2215

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

OpenStreetMap is blocking use of their tile servers whenever Referrer is not included #2215

Description

Activity

hansthen commented on Mar 25, 2026

petervanwylen commented on Mar 26, 2026

hansthen commented on Mar 26, 2026

petervanwylen commented on Mar 26, 2026

breezy-codes commented on Mar 30, 2026

stanislav-a commented on Mar 31, 2026

Julianiolo commented on Mar 31, 2026

hansthen commented on Mar 31, 2026

reory commented on Apr 17, 2026

pprianto commented on Apr 22, 2026

tonny62 commented on Apr 24, 2026

reory commented on Apr 24, 2026

estefano-souza commented on May 4, 2026

kaushikbh99 commented on May 11, 2026

neezr commented on May 14, 2026

Aimmig commented on May 16, 2026

hansthen commented on May 25, 2026

clarisma commented on Sep 2, 2026

junelac commented on Oct 8, 2026

hansthen commented on Oct 8, 2026

hansthen commented on Oct 8, 2026

junelac commented on Oct 9, 2026

hansthen commented on Oct 9, 2026

junelac commented on Oct 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions