Resolviendo "URIError: URI malformed" y errores comunes de URL: Guía Completa

Las URLs (Uniform Resource Locators) son las direcciones de la web. Aunque parecen simples, tienen reglas estrictas sobre qué caracteres están permitidos. Cuando se rompen estas reglas, aparecen errores como URIError: URI malformed, TypeError: Failed to construct 'URL': Invalid URL, o simplemente un enlace roto que lleva a un 404.

En esta guía, profundizaremos en los errores de URL más comunes y cómo resolverlos en JavaScript y otros entornos.

---

1. Mensajes de error de URL comunes

Dependiendo de lo que estés haciendo, podrías encontrar estos errores:

• JavaScript (decodeURIComponent): URIError: URI malformed
• JavaScript (new URL()): TypeError: Failed to construct 'URL': Invalid URL
• Python (urllib): ValueError: Invalid URL
• Java (URLDecoder): java.lang.IllegalArgumentException: URLDecoder: Incomplete % sequence

---

2. Principales causas y soluciones

2.1 "URIError: URI malformed"

Este error ocurre en JavaScript cuando decodeURI() o decodeURIComponent() encuentran una secuencia de codificación porcentual (percent encoding error) que no es válida. Esto suele suceder si un signo % no va seguido de dos dígitos hexadecimales, o si la secuencia representa un carácter UTF-8 inválido.

El Error:

decodeURIComponent("%") // URIError: URI malformed
decodeURIComponent("%E0%A4%A") // URIError: URI malformed (Incompleto)

La Solución:

1. Escapar signos % sueltos: Si tu cadena contiene signos % literales que no son parte de una secuencia codificada, debes escaparlos como %25.
2. Revisar truncamientos: Asegúrate de que la URL no se haya cortado a mitad de una secuencia (por ejemplo, por un límite de campo en la base de datos o un parámetro de consulta muy largo).
3. Usar Try-Catch: Siempre envuelve la decodificación en un bloque try-catch.

function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    console.error("Malformed URL (URL malformada):", str);
    return str; // Devuelve la cadena original si falla la decodificación
  }
}

2.2 encodeURI vs. encodeURIComponent

Un error común es usar la función de codificación incorrecta, lo que provoca errores de "invalid URL" cuando el servidor recibe la solicitud.

• encodeURI(): Se usa para la URL completa. NO codifica caracteres que tienen un significado especial en la estructura de la URL (como :, /, ?, #, &, =).
• encodeURIComponent(): Se usa para parámetros individuales (como una consulta de búsqueda o un nombre de archivo). Codifica todo excepto unos pocos caracteres básicos.

El Error:

const url = "https://example.com/search?q=" + encodeURI("azul/verde");
// Resultado: https://example.com/search?q=azul/verde (El / rompe el parámetro)

La Forma Correcta:

const url = "https://example.com/search?q=" + encodeURIComponent("azul/verde");
// Resultado: https://example.com/search?q=azul%2Fverde (¡Correcto!)

2.3 "TypeError: Invalid URL"

Esto sucede cuando pasas una cadena al constructor URL que no es una URL absoluta válida (por ejemplo, le falta el protocolo como https://).

El Error:

new URL("www.google.com") // TypeError: Invalid URL

La Solución: Asegúrate de que la URL sea absoluta o proporciona una URL base como segundo argumento.

new URL("https://www.google.com") // Correcto
new URL("/ruta", "https://example.com") // Correcto

2.4 Errores de codificación porcentual (Espacios y caracteres especiales)

Las URLs no pueden contener espacios. Aunque algunos navegadores convierten automáticamente los espacios en %20 o +, confiar en este comportamiento es arriesgado.

La Solución: Codifica siempre los datos dinámicos.

• Espacio -> %20 (Estándar)
• Espacio -> + (Solo válido en cadenas de consulta, como ?q=hola+mundo)

---

3. Resolución de problemas avanzada

3.1 Doble codificación (Double Encoding)

Si codificas una cadena dos veces, se convierte en un caos. Por ejemplo, un espacio se convierte en %20, y luego en %2520. Solución: Haz un seguimiento de dónde ocurre la codificación. Codifica los datos solo una vez, justo antes de añadirlos a la URL.

3.2 Codificaciones no UTF-8

La web moderna utiliza UTF-8. Si te encuentras con un sistema antiguo que usa GBK o Latin1 para los parámetros de la URL, decodeURIComponent fallará o producirá "mojibake" (texto basura). Solución: Es posible que necesites una biblioteca como iconv-lite para manejar codificaciones antiguas antes de procesar la URL.

---

4. Prevención y mejores prácticas

1. Usa la API URL: En lugar de concatenar cadenas manualmente, usa las APIs integradas URL y URLSearchParams. Manejan la codificación de forma automática y correcta.
2. Sé específico: Usa encodeURIComponent para los valores de los parámetros y encodeURI para la ruta base.
3. Sanitiza la entrada: Si los usuarios proporcionan URLs, valídalas usando el constructor URL en un bloque try-catch.

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;  
  }
}

---

5. FAQ: Preguntas frecuentes

P: ¿Cuál es la diferencia entre %20 y + para los espacios?

R: %20 es la codificación estándar para el carácter de espacio en cualquier parte de un URI. + es una convención antigua específica para los parámetros de consulta (application/x-www-form-urlencoded). Usa %20 para la máxima compatibilidad.

P: ¿Por qué veo %25 en mi URL?

R: %25 es la versión codificada del propio carácter %. Esto suele ocurrir cuando una URL que ya estaba codificada se codifica de nuevo (doble codificación).

Q: ¿Cómo manejo URLs con Emojis o caracteres no latinos?

R: Usa siempre encodeURIComponent. Convierte correctamente los caracteres Unicode en una secuencia de bytes UTF-8 y luego codifica porcentualmente cada byte.

---

6. Herramienta de comprobación rápida

¿Tienes problemas con una malformed URL? Usa nuestro Codificador y Decodificador de URL. Puede:

• Validar instantáneamente si una URL está bien formada.
• Comparar los resultados de encodeURI y encodeURIComponent.
• Decodificar de forma segura cadenas de consulta complejas.
• Manejar Nombres de Dominio Internacionalizados (IDN).

---

Errores relacionados

• Resolviendo errores de 'Unexpected token in JSON'
• Cómo corregir errores de 'invalid base64 string'
• Entendiendo URIError: URI malformed