Herramientas de desarrollo · Codificador y decodificador de URL
URIError: URI con formato incorrecto: por qué se produce el error decodeURIComponent y cómo solucionarlo
· Cómo funciona
codificación de URL javascript manejo de errores
decodeURIComponent se lanza cuando un signo de porcentaje no va seguido de dos dígitos hexadecimales o cuando los bytes decodificados no son válidos UTF-8. Esta publicación muestra las entradas que lo desencadenan y cómo decodificarlo de manera defensiva.
El signo de porcentaje que falló: por qué se rompe "100% de descuento" decodeURIComponent
Un formulario recoge el código de descuento "100% de descuento". JavaScript pasa esto a decodeURIComponent en un decodificador URL. La función arroja URIError: URI con formato incorrecto. El signo de porcentaje no va seguido de dos dígitos hexadecimales. Esto viola completamente las reglas de codificación porcentual. decodeURIComponent espera que cada % inicie un triplete como %20 o %C3. Un % solitario es un error de sintaxis que detiene la ejecución inmediatamente y genera un error.
Detectar este error de forma segura evita que la aplicación se bloquee por completo. Las URL provienen de la entrada del usuario, redirecciones, códigos QR y correos electrónicos. Los errores tipográficos ocurren con frecuencia. Un informe de fallo con URIError le indica dónde investigar rápidamente. La decodificación defensiva mantiene las aplicaciones en ejecución y los registros de errores resultan útiles para la depuración.
Dos tipos de fallas: escapes hexadecimales mal formados y secuencias de bytes UTF-8 no válidas
decodeURIComponent se produce exactamente en dos situaciones. Primero: secuencia de escape mal formada. Un porcentaje no seguido de dos dígitos hexadecimales (0-9, A-F, a-f). Ejemplos: %ZZ, %2, %2g. Segundo: triplete válido como %E9 decodificación a UTF-8 bytes no válidos. El primero es el error de formato. El segundo es el error semántico. Ambos lanzan y detienen la ejecución inmediatamente.
UTF-8 tiene reglas estrictas sobre secuencias de bytes. Los bytes 0x80–0xFF aparecen solo en secuencias de varios bytes. Un solo %E9 no puede ser válido UTF-8 por sí solo. Este byte huérfano provoca un error. Los errores de formato son obvios. Los errores semánticos son sutiles pero igualmente reales. Ambos casos requieren el manejo de try/catch en el código de producción.
Codificación heredada de un solo byte: cuando %E9 solo se lanza pero %C3%A9 sobrevive
La confusión surge del historial de estándares web. Las páginas antiguas usaban Latin-1 en lugar de UTF-8. En latín-1, %E9 representado é. Los navegadores modernos utilizan UTF-8 exclusivamente. UTF-8 codifica é como %C3%A9. Los decodificadores modernos esperan UTF-8 y rechazan %E9 por tener un formato incorrecto. Este es el comportamiento correcto. El error indica un problema con los datos de origen.
Consenso moderno: UTF-8 en todas partes. El estándar de URL especifica UTF-8. Todos los navegadores actuales utilizan UTF-8. Si encuentra %E9 en sistemas antiguos, detecte el error y recurra a la cadena sin formato. No decodifique como Latin-1 en código moderno. Investigar de dónde se originaron los datos.
Tres entradas, tres mensajes de error: en qué se diferencian los motores en la misma cadena rota
Los motores de los navegadores rechazan la entrada con formato incorrecto de manera consistente, pero los errores de palabras de manera diferente. Chrome informa "URI con formato incorrecto". Firefox informa "secuencia de URI con formato incorrecto". Safari informa que "no se puede convertir un objeto indefinido". Los tres motores rechazan una entrada idéntica. La redacción exacta de los mensajes no está estandarizada en los diferentes motores o versiones. Nunca confíe en el texto de error para guiar la lógica del código.
Nunca haga coincidir cadenas con un mensaje de error para decisiones de programa. Capte siempre el URIError por tipo. La función decodeUrl envuelve decodeURIComponent y proporciona un código coherente INVALID_PERCENT_ENCODING. Esto nombra la posición exacta del problema. Funciona en todos los tiempos de ejecución porque no depende de las variaciones de redacción del motor. Este enfoque es más confiable y mantenible.
Leer la excepción de forma segura: intente /catch, validación y patrones alternativos
Patrón defensivo más simple: envuelva decodeURIComponent en try/catch. Si arroja, use una cadena sin formato o un carácter de reemplazo. Esto evita que la entrada con formato incorrecto falle. Para valores de consulta, muestre el formulario codificado en URL. Para texto de cara al usuario, inserte un carácter de reemplazo. Esto evita que los malos datos dañen las aplicaciones y mantiene la estabilidad.
Validar previamente con expresiones regulares para mayor velocidad y seguridad. Verifique que la entrada contenga solo tripletes %XX válidos antes de decodificar. El patrón /%[0-9A-Fa-f]{2}/g detecta escapes válidos; cualquier cosa que no coincida no es válida. Los errores de formato fallan rápidamente en basura obvia. Los errores UTF-8 aún necesitan probar/catch. En conjunto, esto proporciona una protección defensiva integral contra errores.
Las fallas silenciosas ocultan errores: por qué la decodificación ciega es tan riesgosa como la codificación rota
Riesgo sutil: el decodificador no lanza pero silenciosamente produce texto incorrecto. El código antiguo que utiliza unescape obsoleto deja UTF-8 no válido en la memoria. El texto se ve bien en la pantalla hasta llegar a sistemas que validan estrictamente UTF-8. El código moderno arroja en lugar de corromperse silenciosamente. Una excepción es más clara y segura que la corrupción silenciosa de los datos que se propaga hacia abajo.
Supongamos que la entrada del usuario tiene un formato incorrecto. Termina siempre las llamadas. Registre errores con entrada original para depurar. Nunca asuma que cada % es válido. Los errores tipográficos y el truncamiento crean escapes incompletos. Trátelos como errores de datos, no como errores lógicos. El código defensivo sobrevive con gracia a las malas entradas y mantiene la confiabilidad de los sistemas.
Lo que omiten las herramientas reales: comportamiento del marco del lado del servidor y recuperación de errores
Los marcos de servidor manejan la codificación con formato incorrecto de manera más indulgente que los navegadores. Ruby, Python y PHP ofrecen configuración para manejar escapes no válidos en URL. Algunos sustituyen caracteres de reemplazo automáticamente. Otros dejan caer bytes en silencio. Algunos lanzan excepciones como lo hace JavaScript. El comportamiento real varía según el marco y los ajustes de configuración elegidos por los desarrolladores.
Este artículo cubre únicamente el comportamiento de JavaScript del navegador. Si los valores llegan de las API del servidor, el servidor ya decodificó u omitió errores antes de enviarlos. Los servidores pueden ser más indulgentes que los clientes. Al escribir contratos de API, especifique si los valores están sin formato o predecodificados. Las cadenas de consulta de URL deben llegar codificadas por porcentaje; JSON puede llegar predecodificado.
Validación anticipada: uso del codificador y descodificador de URL para comprobar primero las cadenas sospechosas
Antes de pasar URL sospechosas a decodeURIComponent, péguelas en el codificador y decodificador de URL. La herramienta muestra la codificación exacta, detecta escapes con formato incorrecto y explica los errores sin bloquear la aplicación. Pruebe con %ZZ, %E9 y 100% para ver diferentes fallas y sus mensajes de error exactos. Esto lleva unos segundos y genera confianza.
Valide temprano, detecte errores con elegancia y registre lo que falló. El decodificador defensivo y la herramienta de prueba mantienen las aplicaciones en ejecución y se pueden depurar. El codificador y decodificador de URL convierte el "URI con formato incorrecto" en información procesable que puede utilizar de inmediato. Aplique este patrón a sus propios decodificadores para lograr resiliencia y mantenibilidad en entornos de producción.