Valor inválido X para o atributo “src” no elemento “img”: Carácter ilegal na query

As URLs seguem uma sintaxe rigorosa definida pelo URL Living Standard e RFC 3986. Apenas um conjunto específico de caracteres pode aparecer literalmente numa query string de URL. Caracteres fora deste conjunto — como pipes, parênteses retos, chavetas e outros símbolos — devem ser codificados por percentagem. A codificação por percentagem substitui o carácter por um sinal % seguido do seu código ASCII hexadecimal de dois dígitos.

Quando o W3C HTML Validator encontra uma tag <img> cujo atributo src contém um carácter ilegal na porção query da URL, levanta este erro. A query string é a parte da URL que vem após o carácter ?.

Porque isto é importante

• Inconsistência do navegador: Embora muitos navegadores modernos corrijam silenciosamente URLs malformadas, nem todos os navegadores ou clientes HTTP lidam com caracteres ilegais da mesma forma. Alguns podem interpretar mal a URL ou falhar completamente no carregamento do recurso.
• Conformidade com normas: URLs válidas são um requisito fundamental para conteúdo web interoperável. Usar caracteres ilegais viola tanto as especificações HTML como URL.
• Interoperabilidade: Ferramentas automatizadas, web crawlers, proxies e redes de distribuição de conteúdo podem rejeitar ou danificar URLs que contenham caracteres especiais não codificados, resultando em imagens quebradas.
• Acessibilidade: Leitores de ecrã e tecnologias assistivas dependem de markup válido. URLs malformadas podem causar comportamento inesperado nestas ferramentas.

Caracteres ilegais comuns e as suas codificações

Aqui estão os caracteres frequentemente sinalizados pelo validador:

Como corrigir

Identifique os caracteres ilegais na URL do src e substitua cada um pelo seu valor codificado por percentagem correspondente. Se estiver a gerar URLs dinamicamente com uma linguagem de programação, use a função de codificação URL integrada da linguagem (por exemplo, encodeURI() ou encodeURIComponent() em JavaScript, urlencode() em PHP, urllib.parse.quote() em Python).

Exemplos

❌ Incorreto: carácter pipe não codificado na query string

<img src="https://example.com/image?filter=red|blue" alt="Filtered image">

O carácter | não é permitido literalmente na query string.

✅ Correto: carácter pipe codificado por percentagem

<img src="https://example.com/image?filter=red%7Cblue" alt="Filtered image">

❌ Incorreto: parênteses retos não codificados na query string

<img src="https://example.com/image?size[width]=300&size[height]=200" alt="Resized image">

Os caracteres [ e ] devem ser codificados.

✅ Correto: parênteses retos codificados por percentagem

<img src="https://example.com/image?size%5Bwidth%5D=300&size%5Bheight%5D=200" alt="Resized image">

❌ Incorreto: espaço na query string

<img src="https://example.com/image?caption=hello world" alt="Captioned image">

✅ Correto: espaço codificado por percentagem

<img src="https://example.com/image?caption=hello%20world" alt="Captioned image">

Codificar URLs dinamicamente

Se as suas URLs são construídas em JavaScript, use encodeURIComponent() para valores individuais de parâmetros de query:

const filter = "red|blue";
const url = `https://example.com/image?filter=${encodeURIComponent(filter)}`;
// Resultado: "https://example.com/image?filter=red%7Cblue"

Isto garante que quaisquer caracteres especiais em valores fornecidos pelo utilizador ou dinâmicos são corretamente codificados antes de serem colocados no HTML.

Saiba mais:

MDN Reference

HTML img element - src attribute

→

WHATWG Spec

URL Living Standard

→

web.dev Article

HTML images

→