Resolvendo "invalid UUID format" e erros comuns de UUID: Um Guia Completo

UUIDs (Universally Unique Identifiers) são números de 128 bits usados para identificar informações de forma exclusiva em sistemas de computação. Eles são essenciais para chaves primárias de bancos de dados, IDs de sessão e identificadores de recursos em sistemas distribuídos. Embora pareçam simples strings, eles seguem uma estrutura rigorosa. Quando essa estrutura é violada, você verá erros como invalid input syntax for type uuid, not a valid UUID ou UUID version mismatch.

Neste guia, vamos detalhar a estrutura de um UUID e mostrar como corrigir erros comuns de formatação.

1. Mensagens de Erro Comuns de UUID

Dependendo do seu banco de dados ou linguagem de programação, você pode encontrar estes erros:

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 (Bibliotecas como uuid): TypeError: Invalid UUID

2. Principais Causas e Soluções

2.1 Caractere ou Comprimento Inválido

Um UUID padrão (como a Versão 4) deve ter exatamente 36 caracteres, incluindo quatro hífens. Ele deve conter apenas caracteres hexadecimais (0-9, a-f).

O Erro:

123e4567-e89b-12d3-a456-42661417400 (Muito curto)
123e4567-e89b-12d3-a456-42661417400g (Contém 'g', que não é hexadecimal)
123e4567e89b12d3a456426614174000 (Faltando hífens)

A Solução: Certifique-se de que a string siga o formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Se você tiver uma string de 32 caracteres sem hífens, alguns sistemas permitem, mas para máxima compatibilidade, você deve adicioná-los.

2.2 Incompatibilidade de Versão do UUID (UUID version mismatch)

Existem várias versões de UUIDs (v1, v3, v4, v5, v7). Cada versão tem bits específicos definidos nas posições 13 e 17.

Versão 4 (Aleatória): O 13º caractere deve ser 4, e o 17º caractere deve ser um de 8, 9, a, b.
- Exemplo: ...-4xxx-y... onde y é 8, 9, a ou b.

O Sintoma: Sua aplicação espera um UUID Versão 4, mas recebe um Versão 1 (baseado em tempo), fazendo com que a lógica de validação falhe mesmo que a string "pareça" um UUID, resultando em UUID version mismatch.

2.3 Problemas de Sensibilidade a Maiúsculas e Minúsculas

Embora a especificação UUID diga que eles devem ser representados em minúsculas, alguns sistemas legados ou validadores rigorosos podem falhar se receberem caracteres em maiúsculas.

A Solução: Sempre converta UUIDs para minúsculas antes de armazená-los ou validá-los.

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

3. Solução de Problemas Avançada

3.1 PostgreSQL "invalid input syntax"

Isso geralmente acontece quando você tenta inserir uma string vazia "" ou uma string do tipo null em uma coluna do tipo UUID. Solução: Certifique-se de que sua aplicação envie null (o NULL do SQL) em vez de uma string vazia se o ID estiver ausente.

3.2 Removendo Chaves

Alguns sistemas baseados em Windows ou APIs antigas da Microsoft representam UUIDs (GUIDs) com chaves: {123e4567-e89b-12d3-a456-426614174000}. Solução: Remova as chaves antes de passar a string para uma biblioteca UUID padrão ou um banco de dados moderno.

4. Prevenção e Melhores Práticas

Use um Validador: Sempre valide um UUID antes de realizar operações no banco de dados.

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

Padronize na Versão 4: A menos que você tenha um motivo específico para usar outra versão (como ordenar por tempo com a v7), use a Versão 4 para identificadores de uso geral.
Armazene como Binário (se possível): Em bancos de dados de alto desempenho, armazenar UUIDs como BINARY(16) em vez de CHAR(36) pode economizar um espaço significativo em disco e no tamanho do índice.

5. FAQ: Perguntas Frequentes

Q: Qual é a diferença entre um UUID e um GUID?

A: Para quase todos os propósitos práticos, eles são a mesma coisa. GUID (Globally Unique Identifier) é o termo da Microsoft para o padrão UUID.

Q: Um UUID pode não ser único?

A: Para a Versão 4 (Aleatória), a probabilidade de uma colisão é tão incrivelmente pequena que é considerada zero para todos os propósitos humanos. Você precisaria gerar bilhões de UUIDs por segundo durante séculos para ter 50% de chance de uma única colisão.

Q: É seguro usar UUIDs em URLs?

A: Sim. UUIDs contêm apenas caracteres alfanuméricos e hífens, que são seguros para URLs. Eles são uma ótima maneira de ocultar a contagem real de recursos em seu banco de dados (ao contrário de inteiros de incremento automático).

6. Ferramenta de Verificação Rápida

Está tendo problemas com um ID mal formado? Use nosso Gerador e Validador de UUID. Ele pode:

Validar qualquer UUID e identificar sua versão.
Gerar UUIDs em massa (v1, v4, v7).
Converter entre formatos (Hex, Base64, Binário).
Formatar e normalizar strings de UUID bagunçadas.

Erros Relacionados

Resolvendo erros 'Unexpected token in JSON'
Como corrigir erros 'invalid base64 string'
Resolvendo erros 'invalid regular expression'

Resolvendo 'invalid UUID format' e erros comuns de UUID