Valor incorrecto para el atributo “srcset” en el elemento “img”: URL de imagen candidata incorrecta: Carácter ilegal en la consulta: “[“ no está permitido.

El atributo srcset en los elementos img y source acepta una lista separada por comas de cadenas de imágenes candidatas. Cada candidata consiste en una URL opcionalmente seguida por un descriptor de anchura (ej., 300w) o un descriptor de densidad de píxeles (ej., 2x). La URL en cada candidata debe cumplir con el Estándar de URL, que no permite corchetes sin procesar en la cadena de consulta de una URL HTTP o HTTPS.

Este problema surge comúnmente cuando un framework backend o CMS genera URLs que usan corchetes en los parámetros de consulta — por ejemplo, ?filter[size]=large o ?dimensions[]=300. Aunque muchos navegadores son permisivos y cargarán estas URLs de todos modos, son técnicamente inválidas según la especificación de URL. Usar URLs inválidas puede llevar a un comportamiento impredecible en diferentes navegadores, analizadores HTML y herramientas que procesan tu marcado. También significa que tu HTML falla la validación del W3C, lo que puede enmascarar otros problemas más críticos en tu código.

Tienes dos enfoques principales para solucionarlo:

1. Codifica los corchetes en porcentaje. Reemplaza cada [ con %5B y cada ] con %5D. Esto preserva la estructura de parámetros de consulta prevista mientras hace que la URL cumpla con la especificación. Tu servidor debería interpretar los corchetes codificados en porcentaje de manera idéntica a los corchetes sin procesar.

2. Elimina los corchetes de la URL. Si controlas el código del lado del servidor, considera usar convenciones alternativas de parámetros de consulta que no dependan de corchetes — por ejemplo, usar notación de punto (filter.size=large), valores separados por comas (dimensions=300,400), o nombres de parámetros repetidos (dimension=300&dimension=400).

Al corregir estas URLs, también asegúrate de que cada candidata de imagen siga el formato correcto: una URL válida, seguida de espacios en blanco opcionales y un descriptor, con candidatas separadas por comas.

Ejemplos

Incorrecto — corchetes sin procesar en cadena de consulta

Esto activa el error de validación porque [ y ] aparecen sin codificar en las URLs de 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">

Corregido — corchetes codificados en porcentaje

Reemplazar [ con %5B y ] con %5D hace que las URLs sean válidas:

<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">

Corregido — corchetes eliminados del diseño de URL

Si puedes modificar el enrutamiento del lado del servidor, reestructurar los parámetros de consulta evita el problema por completo:

<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">

Incorrecto — corchetes con descriptores de densidad de píxeles

El mismo problema ocurre independientemente de si usas descriptores de anchura o descriptores de densidad:

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

Corregido — versión codificada en porcentaje

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

Corregido — parámetros de consulta simplificados

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

Más información:

MDN Reference

MDN Web Docs: Responsive images - srcset and sizes

→

MDN Reference

MDN Web Docs: percent-encoding

→