Cómo solucionar "invalid UUID format" y errores comunes de UUID: Guía Completa

Los UUID (Identificadores Únicos Universales) son números de 128 bits utilizados para identificar información de forma única en sistemas informáticos. Son esenciales para claves primarias de bases de datos, IDs de sesión e identificadores de recursos en sistemas distribuidos. Aunque parecen simples cadenas de texto, siguen una estructura estricta. Cuando se viola esta estructura, aparecen errores como invalid input syntax for type uuid, not a valid UUID o UUID version mismatch.

En esta guía, analizaremos la estructura de un UUID y le mostraremos cómo corregir los errores de formato más comunes.

1. Mensajes de error comunes de UUID

Dependiendo de su base de datos o lenguaje de programación, podría encontrar estos:

PostgreSQL: ERROR: invalid input syntax for type uuid: "..."
Python (módulo uuid): ValueError: badly formed hexadecimal UUID string
Java (UUID.fromString): java.lang.IllegalArgumentException: Invalid UUID string: ...
JavaScript (Librerías como uuid): TypeError: Invalid UUID

2. Principales causas y soluciones

2.1 Carácter o longitud inválidos

Un UUID estándar (como la Versión 4) debe tener exactamente 36 caracteres de largo, incluyendo cuatro guiones. Solo debe contener caracteres hexadecimales (0-9, a-f).

El error:

123e4567-e89b-12d3-a456-42661417400 (Demasiado corto)
123e4567-e89b-12d3-a456-42661417400g (Contiene 'g', que no es hexadecimal)
123e4567e89b12d3a456426614174000 (Faltan guiones)

La solución: Asegúrese de que la cadena siga el formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Si tiene una cadena de 32 caracteres sin guiones, algunos sistemas lo permiten, pero para una máxima compatibilidad, debe agregarlos.

2.2 Desajuste de versión de UUID (UUID version mismatch)

Existen varias versiones de UUID (v1, v3, v4, v5, v7). Cada versión tiene bits específicos establecidos en las posiciones 13 y 17.

Versión 4 (Aleatorio): El carácter 13 debe ser 4, y el carácter 17 debe ser uno de 8, 9, a, b.
- Ejemplo: ...-4xxx-y... donde y es 8, 9, a o b.

El síntoma: Su aplicación espera un UUID de Versión 4 pero recibe uno de Versión 1 (basado en tiempo), lo que hace que la lógica de validación falle incluso si la cadena "parece" un UUID, resultando en un UUID version mismatch.

2.3 Problemas de sensibilidad a mayúsculas

Aunque la especificación UUID dice que deben representarse en minúsculas, algunos sistemas heredados o validadores estrictos pueden fallar si reciben caracteres en mayúsculas.

La solución: Convierta siempre los UUID a minúsculas antes de almacenarlos o validarlos.

const cleanUuid = rawUuid.toLowerCase().trim();

3. Solución de problemas avanzada

3.1 PostgreSQL "invalid input syntax"

Esto sucede a menudo cuando intenta insertar una cadena vacía "" o una cadena similar a null en una columna de tipo UUID. Solución: Asegúrese de que su aplicación envíe null (el NULL de SQL) en lugar de una cadena vacía si falta el ID.

3.2 Eliminación de llaves

Algunos sistemas basados en Windows o APIs antiguas de Microsoft representan los UUID (GUID) con llaves: {123e4567-e89b-12d3-a456-426614174000}. Solución: Elimine las llaves antes de pasar la cadena a una librería de UUID estándar o a una base de datos moderna.

4. Prevención y mejores prácticas

Use un validador: Valide siempre un UUID antes de realizar operaciones en la base de datos.

const { validate: validateUuid } = require('uuid');
if (!validateUuid(userInput)) {
  throw new Error("Invalid UUID format");
}

Estandarice en la Versión 4: A menos que tenga una razón específica para usar otra versión (como ordenar por tiempo con v7), use la Versión 4 para identificadores de propósito general.
Almacene como binario (si es posible): En bases de datos de alto rendimiento, almacenar UUIDs como BINARY(16) en lugar de CHAR(36) puede ahorrar un espacio significativo en disco y tamaño de índice.

5. FAQ: Preguntas frecuentes

P: ¿Cuál es la diferencia entre un UUID y un GUID?

R: Para casi todos los propósitos prácticos, son lo mismo. GUID (Globally Unique Identifier) es el término de Microsoft para el estándar UUID.

P: ¿Puede un UUID ser no único?

R: Para la Versión 4 (Aleatorio), la probabilidad de una colisión es tan increíblemente pequeña que se considera cero para todos los propósitos humanos. Necesitaría generar miles de millones de UUIDs por segundo durante siglos para tener un 50% de probabilidad de una sola colisión.

P: ¿Es seguro usar UUIDs en URLs?

R: Sí. Los UUID solo contienen caracteres alfanuméricos y guiones, que son seguros para URLs. Son una excelente manera de ocultar el recuento real de recursos en su base de datos (a diferencia de los enteros autoincrementables).

6. Herramienta de verificación rápida

¿Tiene problemas con un ID mal formado? Use nuestro Generador y Validador de UUID. Puede:

Validar cualquier UUID e identificar su versión.
Generar UUIDs en masa (v1, v4, v7).
Convertir entre formatos (Hex, Base64, Binario).
Formatear y normalizar cadenas de UUID desordenadas.

Errores relacionados

Resolviendo errores 'Unexpected token in JSON'
Cómo corregir errores 'invalid base64 string'
Resolviendo errores 'invalid regular expression'

Cómo solucionar 'invalid UUID format' y errores comunes de UUID