invalid_text_representation invalid input syntax for type uuid: “…” — 22P02

Symptoms

A value being converted to uuid is not a valid 32-hex-digit UUID. PostgreSQL raises SQLSTATE 22P02 (invalid_text_representation).

• UUIDs must be 32 hex digits, optionally hyphenated in 8-4-4-4-12 form.
• Wrong length, non-hex characters, or truncated IDs are rejected.
• Common when a partial or malformed ID reaches the database.

What the server log shows

ERROR:  invalid input syntax for type uuid: "123-not-a-uuid"

Why PostgreSQL raises this — what the manual says

Section 8.12 UUID Type:

“A UUID is written as a sequence of lower-case hexadecimal digits, in several groups separated by hyphens, specifically a group of 8 digits followed by three groups of 4 digits followed by a group of 12 digits, for a total of 32 digits representing the 128 bits.”

The uuid input function parses exactly 128 bits expressed as 32 hex digits (hyphens and braces optional). Any other length or character set is invalid and produces 22P02.

Common causes

• A truncated or concatenated identifier.
• Non-hex characters in the string.
• Passing an integer or arbitrary string where a UUID is expected.

How to fix it

1. Validate/normalize the UUID in the application before sending it.
2. Generate UUIDs with gen_random_uuid() (built in PostgreSQL 13+).
3. Convert empty/placeholder values to NULL instead of an invalid string.

Related & next steps

• SQLSTATE 22P02 — Invalid Text Representation (full reference)
• Message: invalid input syntax for type integer
• Glossary: UUID

Reference: PostgreSQL 18 Section 8.12 “UUID Type”.