Valor incorreto para o atributo “href” no elemento “a”: Caracter ilegal na consulta: “[“ não é permitido.

O Validador HTML W3C verifica que os URLs nos atributos href estão em conformidade com o padrão de URL (definido pelo WHATWG). Embora os colchetes sejam permitidos no componente de host de um URL (para suportar endereços IPv6 como [::1]), eles não são caracteres válidos sem escape na string de consulta — a parte do URL que vem após o ?. Quando o validador encontra um [ ou ] literal na parte de consulta, marca-o como um caracter ilegal.

Esta questão surge comummente quando se trabalha com APIs ou frameworks do lado do servidor que utilizam colchetes em parâmetros de consulta para representar arrays ou estruturas de dados aninhadas. Por exemplo, strings de consulta no estilo PHP como ?filter[name]=foo ou ?ids[]=1&ids[]=2 contêm colchetes que devem ser codificados para HTML válido.

Por que isto importa

• Conformidade com padrões: O WHATWG URL Standard lista explicitamente os colchetes entre os caracteres que devem ser codificados em percentagem nas strings de consulta. URLs inválidos causam falhas na validação W3C.
• Comportamento do browser: Embora a maioria dos browsers modernos seja tolerante e frequentemente lide com colchetes não escapados corretamente, depender desta análise leniente é frágil. Alguns clientes HTTP, proxies ou servidores intermediários podem rejeitar ou danificar URLs com caracteres ilegais.
• Interoperabilidade: URLs codificados são mais seguros quando copiados, partilhados ou processados por ferramentas como verificadores de links, web scrapers ou clientes de email que podem realizar análise rigorosa de URL.

Como corrigir

Substitua cada colchete literal na string de consulta pela sua forma codificada em percentagem:

Se estiver a gerar URLs dinamicamente numa linguagem do lado do servidor ou JavaScript, use a função de codificação apropriada (ex: encodeURIComponent() em JavaScript, urlencode() em PHP, ou urllib.parse.quote() em Python) para lidar com isto automaticamente.

Exemplos

Incorreto: colchetes literais na string de consulta

<a href="https://example.com/search?filter[status]=active">Itens ativos</a>

Isto despoleta o erro de validação porque [ e ] aparecem sem escape na consulta.

Correto: colchetes codificados em percentagem

<a href="https://example.com/search?filter%5Bstatus%5D=active">Itens ativos</a>

Substituir [ por %5B e ] por %5D resolve o erro. O servidor que recebe este pedido irá descodificar os valores de volta para filter[status]=active.

Incorreto: parâmetros no estilo array com colchetes

<a href="/api/items?ids[]=1&ids[]=2&ids[]=3">Carregar itens</a>

Correto: parâmetros no estilo array codificados

<a href="/api/items?ids%5B%5D=1&amp;ids%5B%5D=2&amp;ids%5B%5D=3">Carregar itens</a>

Note que além de codificar os colchetes, os caracteres & nos atributos HTML devem ser escritos como & para markup completamente válido.

Incorreto: colchetes num valor simples

<a href="search.html?q=[value]">Pesquisar</a>

Correto: colchetes codificados num valor simples

<a href="search.html?q=%5Bvalue%5D">Pesquisar</a>

Nota sobre colchetes no host (uso válido)

Os colchetes são válidos na parte host de um URL para endereços IPv6. O seguinte não despoleta o erro:

<a href="http://[::1]:8080/page">IPv6 localhost</a>

O validador apenas marca colchetes que aparecem na string de consulta ou outras partes do URL onde não são permitidos.

Saiba mais:

MDN Reference

MDN Web Docs: Percent-encoding

→

MDN Reference

HTML a element - href attribute

→

MDN Reference

What is a URL?

→

MDN Reference

encodeURI() - JavaScript

→