Back to Blog

Why Your WMS Will Not Load in a Browser

You pasted a WMS URL that works. It works in QGIS. It does not work in your web map, and the error is either nothing at all or a sentence that sounds like the server is down when it plainly is not.

Every one of these has a boring, specific cause. This post walks them in the order a browser hits them, using the messages our own WMS / WMTS viewer shows: one per failure, not a single "could not load".

First, open the capabilities URL in a plain browser tab: XML means the host is reachable and the problem is the answer, or CORS; an error page or nothing means the problem is the request.

Mixed content: the service speaks plain HTTP and your page does not

The symptom arrives before any request leaves: This service only answers on http://, and your browser blocks that on this secure page — including the map tiles. No proxy can fix this for you; the service operator needs to enable HTTPS.

A secure page may not pull subresources over an insecure scheme, and the tiles are subresources too — so even a fetched layer list would not help: every GetMap is blocked the same way (mixed content).

  • Try the secure address. Many services answer on both schemes and publish only the insecure one; the viewer offers it beside the error, labelled Try the https:// address.
  • Proxy it from your own server. The only real fix when the service has no secure endpoint at all.
  • Ask the operator to enable TLS. Slow, but it helps everyone after you.

CORS: the request left, and the browser threw the answer away

This one costs people an afternoon, because every tool they reach for says the server is fine. The symptom is a failure with no status code, and it has two arms. If the host is reachable: This server is online, but it does not allow cross-origin requests from a browser (CORS), so its layer list cannot be read here — the tiles may still work. Geodocs reads services like this through its own server. If it is not: We could not reach this server at all — it may be offline, unreachable, or the address may be wrong.

The cause: the request went out, the server answered, and because the response carried no access-control-allow-origin header naming your origin, the browser discarded it before your code saw a byte. It is a browser rule about what a page may read, so by the server's own lights nothing went wrong (CORS on MDN).

This is why the service works in QGIS and fails in your web app, and neither one is broken. QGIS is not a browser: it has no origin, so there is nothing to check and nothing to refuse — same for curl and for your own backend. "But it works in QGIS" is evidence for the CORS diagnosis, not against it.

  • Put a server in the path. Your backend fetches the capabilities document and the tiles and serves them from your own origin, so nothing is cross-origin any more.
  • Get the operator to send the header. One access-control-allow-origin fixes it for every browser client they will have.

The server answered with an error code

The symptom carries the number: The server answered with an error ({status}). Check the address and try again. — the placeholder carries the real status. The cause is usually the address:

  • A path segment that is not the service. Portals publish a landing page and an endpoint differing by one element; the landing page 404s.
  • A missing query string. Some servers need SERVICE=WMS&REQUEST=GetCapabilities spelled out, and answer 400 rather than redirecting.
  • A 403 that is about your client, not your request — see the user-agent section below.
  • A 500 on the version you asked for. Dropping VERSION=1.3.0, or setting it to 1.1.1, changes the answer on more servers than it should.

Read the body, not the number: HTML means a portal is talking to you, XML means the service is, and the XML names the parameter it did not like.

It answered, but not with XML — or not with capabilities

Two adjacent symptoms, one cause. If the body does not parse as XML at all: That address answered, but not with a valid XML document. If it parses but its root element is not one the tool recognises: That address answered, but not with an OGC capabilities document.

Both usually mean you asked a web page for capabilities and got a web page — a login wall, a "temporarily unavailable" notice, a captive portal. The status is fine; the body was written for a human.

The subtle member of the family: when a WMS refuses at the OGC level it answers with a ServiceExceptionReport, perfectly valid XML whose root is not a capabilities root — so the viewer calls it not-an-OGC-document rather than an exception. Open it: it says why.

A WMTS address in the WMS box

The symptom names what it found: This looks like a {found} service, not the one you selected. — upper-cased, as WMTS or WFS.

WMS, WMTS and WFS are three protocols people talk about as one thing, and the wrong choice is not a typo you can see in the URL — which is why the tool reads the document and tells you which it is. Switch the selector and reconnect, but know which you want: WMS renders an image of the bounding box you ask for, WMTS serves pre-rendered tiles on a fixed grid and is faster, WFS returns features (OGC WMS).

It took too long, or the document was too big

Two caps, two sentences. On time: This took longer than 30 seconds to answer. Some capabilities documents are several megabytes — you can try again. On size: The server's answer was too large to load safely and was stopped partway through. Try a smaller area or a more specific layer.

Neither is arbitrary: on some national services a capabilities document carries tens of thousands of layers and megabytes of XML, and a tab that parses one blocks while it does. Retrying works more often than you would think, because these servers are slow on a cold cache. If it never finishes, a backend that caches the document once is the only answer.

It connected, but the layer will not draw

A separate family covers the gap between connecting and rendering. A layer the map cannot project: This layer has no coordinate system the map can use. A service offering only formats it cannot draw: This service offers no image format the map can render. A WMTS layer with no usable grid: This layer has no tile matrix set the map can use. A layer id the document does not contain: This layer id is not in the service's capabilities.

These are the honest ones: the service answered, the document parsed, and this layer declares nothing the renderer can work with. It happens most with older national services that publish a local projected CRS and no Web Mercator, and with layer ids copied from a document that has since changed.

The server refuses your client, not your request

This one produces a confident, wrong diagnosis. Some servers decide what to send from your User-Agent string, and not all the same way. Probing two batches of data sources on 11 September 2026 — sixteen elevation hosts and eight raster-sample hosts — turned up three distinct behaviours:

  • Refuses a generic Mozilla/5.0, serves a browser and curl. naturalearthdata.com answers a plain curl request with 200 and refuses a bare Mozilla/5.0 with 406 — a bot rule firing on the generic token, not on scripts.
  • Refuses both, serves a real browser. www.usgs.gov refuses curl and a bare Mozilla/5.0 with 403, and answers 200 to a full Chrome user-agent string. Nothing is gated; the refusal was an artefact of how we asked.
  • Refuses everything we could point at it. The IBGE portal answers a Cloudflare interstitial to every client we tried, a full Chrome user-agent string included — whether a real browser gets through is not something a script can prove from here.

It runs the other way too: re-checked today, Digital Earth Africa's WMS answers 200 to a bare user-agent and 403 to a full Chrome string, so a desktop client is fine and a browser app in Chrome or Edge is blocked. A status code from a shell script is a fact about that script, not about the service.

Reading a GetCapabilities failure by its root element

When a capabilities request goes wrong, look at the first element of the body. It is a five-way classification that tells you which section above you are in:

  • WMS_Capabilities or WMT_MS_Capabilities — a WMS capabilities document, 1.3.0 and 1.1.1 respectively. This is success.
  • Capabilities in the WMTS namespace — a WMTS capabilities document. Success, on the other protocol.
  • WFS_Capabilities — a WFS. Features, not pictures.
  • ServiceExceptionReport or ExceptionReport — the service refused and says why. Read the element inside; it names the parameter.
  • html, or a DOCTYPE — a page for a human. A login wall, a portal, an error page from something in front of the service.

Finding the word "Exception" in the body proves nothing. A valid capabilities document legitimately contains an Exception element listing the formats the service reports errors in, so grepping for it is how people convince themselves a working service is broken. Classify by the root element, never by a substring.

Test files you can use

These are endpoints rather than files — something known-good to test against, so you can tell "my code is wrong" from "this service is wrong". Every line was re-probed on 11 September 2026 from a script sending an Origin header; a probe result is one moment from one address, which is why it carries the date.

  • EOX Maps, WMTS — , 200, root Capabilities, echoing the requesting origin back in access-control-allow-origin. Open and usable from a browser app; licensed by EOX, so check their terms first.
  • terrestris OSM, WMS — , 200, root WMS_Capabilities, access-control-allow-origin: *. Open; OpenStreetMap data under ODbL, so attribution is required.
  • Digital Earth Africa, WMS — 200 to a script, 403 to a full Chrome user-agent, today. Fine in QGIS, unusable from a browser app in Chrome or Edge.
  • Famous and broken, so you stop looking — the OneGeology global portal is on every "free WMS" list, and its certificate still does not match its hostname. Every client refused it today, and no proxy fixes that.

For more, use the list of free WMS and WMTS services — the full set, with a per-entry status.

When nothing works: QGIS, ogr2ogr, and the tool's own presets

If you have been through every section and it still will not load, change client. That is what tells you which half of the problem you have.

  • Open it in QGIS. Paste the base URL into a new WMS/WMTS connection. If the layer list populates, the service is healthy and your problem is a browser rule — CORS or mixed content, fixed with a server in the path.
  • Fetch it with GDAL. The GDAL WMS driver reads a WMS as a raster source from the command line, with no origin and no browser rules in the way; for a WFS, ogr2ogr pulls the features into a file.
  • Try a service you know works. The viewer ships three presets, each verified in a real browser from a real origin rather than from a script: EOX Sentinel-2 cloudless over WMTS, terrestris OpenStreetMap over WMS, USGS topographic over WMS. If one loads and your URL does not, the difference is in the URL.

If you would rather not maintain a proxy for the services that break CORS, a cache for the slow ones, and a list of which is which, that is what Geodocs does.

Related Articles

Navegação