Voltar ao Blog

Por Que Seu WMS Não Carrega no Navegador

Você colou uma URL de WMS que funciona. Funciona no QGIS. Não funciona no seu mapa web, e o erro é ou nada, ou uma frase que soa como se o servidor estivesse fora do ar quando claramente não está.

Cada um desses casos tem uma causa chata e específica. Este post percorre todos eles na ordem em que um navegador os encontra, usando as mensagens do nosso próprio visualizador de WMS / WMTS: uma por falha, não um "não foi possível carregar" genérico.

Primeiro, abra a URL de capabilities numa aba de navegador simples: XML significa que o host está acessível e o problema está na resposta, ou é CORS; uma página de erro ou nada significa que o problema está na requisição.

Conteúdo misto: o serviço fala HTTP simples e sua página não

O sintoma aparece antes de qualquer requisição sair: Este serviço só responde em http://, e seu navegador bloqueia isso nesta página segura — inclusive os tiles do mapa. Nenhum proxy resolve isso para você; quem opera o serviço precisa habilitar HTTPS.

Uma página segura não pode buscar subrecursos por um esquema inseguro, e os tiles também são subrecursos — então mesmo uma lista de camadas obtida não ajudaria: toda chamada GetMap é bloqueada do mesmo jeito (conteúdo misto).

  • Tente o endereço seguro. Muitos serviços respondem nos dois esquemas e publicam só o inseguro; o visualizador oferece o outro ao lado do erro, com o rótulo Tentar o endereço https://.
  • Coloque um proxy no seu próprio servidor. A única correção de verdade quando o serviço simplesmente não tem endpoint seguro nenhum.
  • Peça para quem opera o serviço habilitar TLS. Lento, mas ajuda todo mundo depois de você.

CORS: a requisição saiu, e o navegador jogou a resposta fora

Este aqui custa uma tarde inteira para muita gente, porque toda ferramenta a que você recorre diz que o servidor está bem. O sintoma é uma falha sem código de status, e tem dois braços. Se o host está acessível: Este servidor está no ar, mas não permite requisições entre origens vindas de um navegador (CORS), então a lista de camadas não pode ser lida aqui — os tiles ainda podem funcionar. O Geodocs lê serviços assim pelo próprio servidor. Se não está: Não conseguimos alcançar este servidor de jeito nenhum — ele pode estar fora do ar, inacessível, ou o endereço pode estar errado.

A causa: a requisição saiu, o servidor respondeu, e como a resposta não trazia um cabeçalho access-control-allow-origin nomeando a sua origem, o navegador descartou ela antes do seu código ver um único byte. É uma regra do navegador sobre o que uma página pode ler, então, pelo ponto de vista do próprio servidor, nada deu errado (CORS no MDN).

É por isso que o serviço funciona no QGIS e falha na sua aplicação web, e nenhum dos dois está quebrado. O QGIS não é um navegador: não tem origem, então não há nada para checar e nada para recusar — o mesmo vale para o curl e para o seu próprio backend. "Mas funciona no QGIS" é evidência a favor do diagnóstico de CORS, não contra ele.

  • Coloque um servidor no meio do caminho. O seu backend busca o documento de capabilities e os tiles e serve eles a partir da sua própria origem, então nada mais é cross-origin.
  • Peça para quem opera o serviço enviar o cabeçalho. Um único access-control-allow-origin resolve para todo cliente de navegador que ele vier a ter.

O servidor respondeu com um código de erro

O sintoma carrega o número: O servidor respondeu com um erro ({status}). Confira o endereço e tente de novo. — o placeholder carrega o status real. A causa costuma estar no endereço:

  • Um segmento de caminho que não é o serviço. Portais publicam uma página de apresentação e um endpoint que diferem por um elemento só; a página de apresentação dá 404.
  • Uma query string faltando. Alguns servidores exigem SERVICE=WMS&REQUEST=GetCapabilities escrito por extenso, e respondem 400 em vez de redirecionar.
  • Um 403 que é sobre o seu cliente, não sobre a sua requisição — veja a seção sobre user agent mais abaixo.
  • Um 500 na versão que você pediu. Tirar o VERSION=1.3.0, ou trocar para 1.1.1, muda a resposta em mais servidores do que deveria.

Leia o corpo, não o número: HTML significa que quem está falando é um portal, XML significa que é o serviço, e o XML nomeia o parâmetro que ele não gostou.

Respondeu, mas não com XML — ou não com capabilities

Dois sintomas vizinhos, uma causa só. Se o corpo não dá parse como XML de jeito nenhum: Esse endereço respondeu, mas não com um documento XML válido. Se dá parse mas o elemento raiz não é um que a ferramenta reconhece: Esse endereço respondeu, mas não com um documento de capabilities OGC.

Os dois geralmente significam que você pediu capabilities e recebeu uma página web — um muro de login, um aviso de "temporariamente indisponível", um portal cativo. O status está ok; o corpo foi escrito para um humano.

O membro sutil da família: quando um WMS recusa no nível do próprio OGC, ele responde com um ServiceExceptionReport, um XML perfeitamente válido cuja raiz não é uma raiz de capabilities — então o visualizador chama isso de não-é-um-documento-OGC, em vez de exceção. Abra o documento: ele diz o motivo.

Um endereço de WMTS na caixa de WMS

O sintoma nomeia o que encontrou: Isso parece um serviço {found}, não o que você selecionou. — em maiúsculas, como WMTS ou WFS.

WMS, WMTS e WFS são três protocolos que as pessoas tratam como se fossem um só, e a escolha errada não é um erro de digitação visível na URL — por isso a ferramenta lê o documento e diz qual dos três é. Troque o seletor e reconecte, mas saiba qual você quer: o WMS renderiza uma imagem do bounding box que você pede, o WMTS serve tiles pré-renderizados numa grade fixa e é mais rápido, o WFS devolve feições (WMS da OGC).

Demorou demais, ou o documento era grande demais

Dois limites, duas frases. No tempo: Isso demorou mais de 30 segundos para responder. Alguns documentos de capabilities têm vários megabytes — você pode tentar de novo. No tamanho: A resposta do servidor era grande demais para carregar com segurança e foi interrompida no meio do caminho. Tente uma área menor ou uma camada mais específica.

Nenhum dos dois é arbitrário: em alguns serviços nacionais, um documento de capabilities carrega dezenas de milhares de camadas e megabytes de XML, e uma aba que faz parse disso trava enquanto processa. Tentar de novo funciona mais vezes do que você imagina, porque esses servidores são lentos com o cache frio. Se nunca termina, um backend que guarda o documento em cache uma vez é a única resposta.

Conectou, mas a camada não desenha

Uma família separada cobre o vão entre conectar e renderizar. Uma camada que o mapa não consegue projetar: Esta camada não tem um sistema de coordenadas que o mapa possa usar. Um serviço que só oferece formatos que ele não consegue desenhar: Este serviço não oferece nenhum formato de imagem que o mapa possa renderizar. Uma camada WMTS sem grade utilizável: Esta camada não tem um conjunto de matrizes de tiles que o mapa possa usar. Um id de camada que o documento não contém: Este identificador de camada não está nas capabilities do serviço.

Esses são os honestos: o serviço respondeu, o documento deu parse, e essa camada não declara nada com que o renderizador consiga trabalhar. Acontece mais com serviços nacionais antigos que publicam um CRS projetado local e nenhum Web Mercator, e com ids de camada copiados de um documento que já mudou desde então.

O servidor recusa o seu cliente, não a sua requisição

Este produz um diagnóstico confiante e errado. Alguns servidores decidem o que enviar a partir da sua string User-Agent, e nem todos da mesma forma. Testar dois lotes de fontes de dados em 11 de setembro de 2026 — dezesseis hosts de elevação e oito hosts de rasters de exemplo — revelou três comportamentos distintos:

  • Recusa um Mozilla/5.0 genérico, atende um navegador e o curl. naturalearthdata.com responde 200 a uma requisição de curl simples e recusa com 406 um Mozilla/5.0 puro — uma regra antibot disparando no token genérico, não em scripts.
  • Recusa os dois, atende um navegador de verdade. www.usgs.gov recusa o curl e um Mozilla/5.0 puro com 403, e responde 200 a uma string de user agent do Chrome completa. Nada está bloqueado de fato; a recusa foi um artefato de como perguntamos.
  • Recusa tudo o que a gente conseguiu apontar para ele. O portal do IBGE responde com um desafio da Cloudflare para todo cliente que testamos, inclusive uma string de user agent do Chrome completa — se um navegador de verdade passa é algo que nenhum script consegue provar daqui.

Também acontece ao contrário: reconferido hoje, o WMS do Digital Earth Africa responde 200 a um user agent simples e 403 a uma string do Chrome completa, então um cliente desktop funciona bem e uma aplicação de navegador no Chrome ou no Edge fica bloqueada. Um código de status vindo de um shell script é um fato sobre esse script, não sobre o serviço.

Lendo uma falha de GetCapabilities pelo elemento raiz

Quando uma requisição de capabilities dá errado, olhe o primeiro elemento do corpo. É uma classificação de cinco vias que diz em qual seção acima você está:

  • WMS_Capabilities ou WMT_MS_Capabilities — um documento de capabilities de WMS, das versões 1.3.0 e 1.1.1 respectivamente. Isso é sucesso.
  • Capabilities no namespace do WMTS — um documento de capabilities de WMTS. Sucesso, no outro protocolo.
  • WFS_Capabilities — um WFS. Feições, não imagens.
  • ServiceExceptionReport ou ExceptionReport — o serviço recusou e diz o motivo. Leia o elemento de dentro; ele nomeia o parâmetro.
  • html, ou um DOCTYPE — uma página para um humano. Um muro de login, um portal, uma página de erro de algo na frente do serviço.

Encontrar a palavra "Exception" no corpo não prova nada. Um documento de capabilities válido contém legitimamente um elemento Exception que lista os formatos em que o serviço reporta erros, então fazer grep por ela é como as pessoas se convencem de que um serviço funcionando está quebrado. Classifique pelo elemento raiz, nunca por uma substring.

Arquivos de teste que você pode usar

Estes aqui são endpoints, não arquivos — algo que você sabe que funciona, para usar como referência e distinguir "meu código está errado" de "esse serviço está errado". Cada linha foi retestada em 11 de setembro de 2026 por um script que envia um cabeçalho Origin; um resultado de teste é um instante a partir de um endereço, por isso carrega a data.

  • EOX Maps, WMTS — , 200, raiz Capabilities, ecoando a origem da requisição de volta em access-control-allow-origin. Aberto e utilizável a partir de uma aplicação de navegador; licenciado pela EOX, então confira os termos deles antes.
  • terrestris OSM, WMS — , 200, raiz WMS_Capabilities, access-control-allow-origin: *. Aberto; dados do OpenStreetMap sob ODbL, então atribuição é obrigatória.
  • Digital Earth Africa, WMS — 200 para um script, 403 para um user agent do Chrome completo, hoje. Funciona bem no QGIS, inutilizável a partir de uma aplicação de navegador no Chrome ou no Edge.
  • Famoso e quebrado, para você parar de procurar — o portal global do OneGeology está em toda lista de "WMS gratuito", e o certificado dele continua não correspondendo ao hostname. Todo cliente recusou ele hoje, e nenhum proxy resolve isso.

Para mais, use a lista de serviços WMS e WMTS gratuitos — o conjunto completo, com status por item.

Quando nada funciona: QGIS, ogr2ogr e os presets da própria ferramenta

Se você já passou por cada seção e ainda assim não carrega, troque de cliente. É isso que diz qual metade do problema você tem.

  • Abra no QGIS. Cole a URL base numa nova conexão WMS/WMTS. Se a lista de camadas aparecer, o serviço está saudável e o seu problema é uma regra de navegador — CORS ou conteúdo misto, corrigido com um servidor no meio do caminho.
  • Busque com o GDAL. O driver WMS do GDAL lê um WMS como uma fonte raster pela linha de comando, sem origem e sem regra de navegador no caminho; para um WFS, o ogr2ogr puxa as feições para um arquivo.
  • Tente um serviço que você sabe que funciona. O visualizador vem com três presets, cada um verificado num navegador de verdade a partir de uma origem real, não de um script: Sentinel-2 sem nuvens da EOX sobre WMTS, OpenStreetMap da terrestris sobre WMS, topográfico da USGS sobre WMS. Se um carrega e a sua URL não, a diferença está na URL.

Se você preferir não manter um proxy para os serviços que quebram por CORS, um cache para os lentos, e uma lista de qual é qual, é isso que o Geodocs faz.

Artigos Relacionados

Navegação