Why Is My UUID Invalid? Common Errors and Fixes

Typical Error Messages

Exact wording varies by version, but the causes are the same.

Cause 1: Hidden Whitespace and Invisible Characters

Copying from emails, spreadsheets, PDFs or chat apps often brings extra characters:

• Leading or trailing spaces and tabs
• Line breaks (\n, \r\n) from copying a whole cell or line
• Non-breaking spaces (U+00A0)
• Zero-width spaces (U+200B) or byte order marks

The UUID looks perfect on screen but has 37 or 38 characters. Fix: trim input before validating, and in data pipelines strip all whitespace and zero-width characters from ID fields.

Cause 2: Wrong Length

A valid UUID has exactly 32 hex digits (36 characters with hyphens). Common length problems:

• Truncation by a database column that's too short, a UI that shortens long text, or a log line cut off.
• Missing characters from manual typing.
• Extra characters from accidentally pasting two IDs together.

Count the hex digits, ignoring hyphens. If it's not 32, the value is damaged and needs to be fetched again from the source.

Cause 3: Characters That Aren't Hex

Only 0–9 and a–f (either case) are allowed. Look for:

• Letter O instead of zero, and lowercase L or capital I instead of one, often from retyping.
• Smart quotes or dashes: word processors replace - with en dashes (–) and wrap text in curly quotes.
• Quotes included in the value, such as "9b2c1f7e-..." with literal quote marks after a CSV import.

Cause 4: A Format the Parser Doesn't Accept

Parsers differ:

• PostgreSQL accepts hyphens in standard positions, braces and the compact form, but not arbitrary hyphen placement.
• .NET's Guid.Parse accepts several formats; ParseExact with "D" only accepts the standard hyphenated form.
• Some APIs require lowercase canonical form only.

If a value works in one system and fails in another, compare their accepted formats. Normalise to lowercase hyphenated form before sending. UUID format explained lists the common forms.

Cause 5: Strict Version or Variant Checks

A correctly formatted UUID can still fail validation that requires a specific version, for example a v4-only regex receiving UUID v7 values after a system upgrade, or a strict check rejecting the nil UUID. Check the 13th digit (version) and 17th (variant). UUID regex patterns has version-agnostic patterns, and nil UUID and max UUID explains the special values.

Cause 6: Not a UUID at All

Sometimes the field contains something else entirely: a numeric ID, a ULID, a slug, or an object serialised as [object Object]. Check where the value came from and whether the API expects a UUID for that field.

A Quick Debugging Checklist

1. Print the value with delimiters, such as [${value}], to reveal whitespace.
2. Print its length; it should be 36 (or 32 without hyphens).
3. Check for characters outside 0-9a-fA-F-.
4. Compare the format with what the receiving system accepts.
5. Check version and variant if a strict validator is involved.

In code, prefer robust validation at the edges of your system; how to validate a UUID in JavaScript and Python shows how.

Checking Many Values at Once

When an import or migration fails, you often need to know which IDs are bad. Paste them into the UUID validator: it checks up to 1,000 lines, skips blank lines, accepts standard, compact, braced and URN forms, and shows which lines are invalid along with the canonical form of the valid ones. For a single suspicious value, the UUID decoder shows its version, variant and any embedded timestamp.

Summary

Most invalid UUIDs are damaged by whitespace, truncation, look-alike characters or unsupported formats. Trim, count, check characters, normalise, and only then worry about version and variant rules.