Valor incorreto para o atributo “srcset” no elemento “img”: URL de candidato de imagem incorreto: Caráter ilegal na consulta: “[“ não é permitido.

O atributo srcset nos elementos img e source aceita uma lista separada por vírgulas de strings candidatas de imagem. Cada candidato consiste numa URL opcionalmente seguida por um descritor de largura (por exemplo, 300w) ou um descritor de densidade de pixels (por exemplo, 2x). A URL em cada candidato deve estar em conformidade com o Padrão URL, que não permite colchetes brutos na string de consulta de uma URL HTTP ou HTTPS.

Este problema surge frequentemente quando uma framework de backend ou CMS gera URLs que usam colchetes em parâmetros de consulta — por exemplo, ?filter[size]=large ou ?dimensions[]=300. Embora muitos navegadores sejam tolerantes e carreguem estes URLs de qualquer forma, eles são tecnicamente inválidos de acordo com a especificação URL. Usar URLs inválidos pode levar a comportamento imprevisível em diferentes navegadores, analisadores HTML e ferramentas que processam o seu markup. Também significa que o seu HTML falha a validação W3C, o que pode mascarar outros problemas mais críticos no seu código.

Você tem duas abordagens principais para corrigir isto:

1. Codificar os colchetes em percentagem. Substitua cada [ por %5B e cada ] por %5D. Isto preserva a estrutura pretendida do parâmetro de consulta enquanto torna a URL conforme à especificação. O seu servidor deve interpretar colchetes codificados em percentagem de forma idêntica aos colchetes brutos.

2. Eliminar colchetes da URL. Se você controlar o código do lado do servidor, considere usar convenções alternativas de parâmetros de consulta que não dependam de colchetes — por exemplo, usando notação por pontos (filter.size=large), valores separados por vírgulas (dimensions=300,400), ou nomes de parâmetros repetidos (dimension=300&dimension=400).

Ao corrigir estes URLs, certifique-se também de que cada candidato de imagem segue o formato correto: uma URL válida, seguida por espaço opcional e um descritor, com candidatos separados por vírgulas.

Exemplos

Incorreto — colchetes brutos na string de consulta

Isto desencadeia o erro de validação porque [ e ] aparecem não codificados nos URLs srcset:

<img
  src="photo.jpg"
  srcset="photo.jpg?crop[width]=400 400w, photo.jpg?crop[width]=800 800w"
  sizes="(max-width: 600px) 400px, 800px"
  alt="A landscape photo">

Corrigido — colchetes codificados em percentagem

Substituir [ por %5B e ] por %5D torna os URLs válidos:

<img
  src="photo.jpg"
  srcset="photo.jpg?crop%5Bwidth%5D=400 400w, photo.jpg?crop%5Bwidth%5D=800 800w"
  sizes="(max-width: 600px) 400px, 800px"
  alt="A landscape photo">

Corrigido — colchetes removidos do design da URL

Se você puder modificar o roteamento do lado do servidor, reestruturar os parâmetros de consulta evita completamente o problema:

<img
  src="photo.jpg"
  srcset="photo.jpg?crop_width=400 400w, photo.jpg?crop_width=800 800w"
  sizes="(max-width: 600px) 400px, 800px"
  alt="A landscape photo">

Incorreto — colchetes com descritores de densidade de pixels

O mesmo problema ocorre independentemente de você usar descritores de largura ou descritores de densidade:

<img
  src="avatar.jpg"
  srcset="avatar.jpg?size=[sm] 1x, avatar.jpg?size=[lg] 2x"
  alt="User avatar">

Corrigido — versão codificada em percentagem

<img
  src="avatar.jpg"
  srcset="avatar.jpg?size=%5Bsm%5D 1x, avatar.jpg?size=%5Blg%5D 2x"
  alt="User avatar">

Corrigido — parâmetros de consulta simplificados

<img
  src="avatar.jpg"
  srcset="avatar.jpg?size=sm 1x, avatar.jpg?size=lg 2x"
  alt="User avatar">

Saiba mais:

MDN Reference

MDN Web Docs: Responsive images - srcset and sizes

→

MDN Reference

MDN Web Docs: percent-encoding

→