Debugging MongoDB UUID encoding issues

September 29, 2026 · 15 min read

MongoDB Compass, mongosh, and application logs often surface the same frustrating message: Invalid UUID format. The ID you copied from a ticket looks perfect - 36 characters, four hyphens, lowercase hex - yet a query, aggregation stage, or ODM validator rejects it. In most cases the data is not corrupt; the encoding is wrong for the operation you are running. This guide walks through the failure modes that cause UUID encoding bugs in MongoDB and how to move from ERROR to FIXED without guessing.

Encoding issues cluster around three axes: whether the field is stored as a string or BSON Binary, which subtype (03 legacy GUID vs 04 RFC 4122) those sixteen bytes use, and whether multiple services stringify the same binary differently. Treat debugging as byte-order detective work, not string editing.

When you see Invalid UUID format

$toUUID, strict schema validators, and some drivers throw when input is not a canonical RFC string or when binary subtype does not match expectations. Common triggers: passing a 32-character hex string without hyphens, uppercase mixed with lowercase in inconsistent ways, wrapping braces from .NET ({550e8400-...}), or feeding Extended JSON base64 into an API that expects only hyphenated text.

Another frequent cause is comparing a string field to a Binary UUID in a filter. MongoDB does not coerce between them; { _id: "550e8400-e29b-41d4-a716-446655440000" } will not match Binary(subtype:4, ...) even when humans see the same ID. The error may appear on the client as “invalid UUID” when the real issue is type mismatch.

// Wrong: string query against binary _id
await db.users.findOne({
  _id: "550e8400-e29b-41d4-a716-446655440000",
});

// Right: BSON UUID type
import { UUID } from "mongodb";
await db.users.findOne({
  _id: new UUID("550e8400-e29b-41d4-a716-446655440000"),
});

String vs Binary: pick one per collection

Strings are easy to read in logs but easy to break: duplicate keys with different casing, missing hyphens, and 36-byte index entries. Binary subtype 04 is the production default for _id and foreign keys - compact, bytewise equality, and unambiguous semantics. If your collection is mixed, export a sample with mongoexport --jsonFormat=canonical and count how many documents use $binary vs quoted strings.

Migration path: add a temporary field with the canonical binary form, backfill in batches, switch readers, then drop string _id only after referential integrity checks pass. Never flip types in place on a live primary key without updating every foreign key in the same maintenance window.

Subtype 03 vs 04 and endianness

Subtype 0x04 stores RFC 4122 byte order. Subtype 0x03 follows legacy Microsoft GUID layout - same logical UUID, different permutation of the first twelve bytes. A C# service writing 03 and a Node service reading 04 produces “invalid” joins: Compass may display a friendly UUID while your API searches for a different binary value.

When hex dumps disagree only in the first 12 bytes and the last 8 match, you have endianness, not corruption. Use a conversion tool to translate between representations before rewriting data. See our guides on subtype 03 vs 04 and fixing endianness for migration patterns.

A repeatable debug workflow

Export one failing document as Extended JSON; note subType and base64 payload.
Decode to hex and compare with an RFC 4122 encoder from the canonical string.
Log the runtime type your driver sends (typeof _id, constructor.name).
Reproduce the query in mongosh with explicit UUID("...") syntax.
Check driver UUID representation settings (Java LEGACY vs STANDARD, .NET GuidRepresentation).
Add a contract test with fixed vectors in CI for each language in your stack.

Paste the canonical string and raw base64 into the MongoDB UUID converter to see subtype 03 and 04 side by side before you run a one-off migration script. Validate partner-supplied strings with the UUID validator so bad input never reaches insert.

Prevention checklist for new services

Schema rule: _id and FK fields are BSON UUID subtype 04 unless integrating with legacy 03.
Ban string UUID primary keys in code review for new collections.
Document UUID representation in OpenAPI and README for every microservice.
Log canonical strings plus subtype in structured logs during integration testing only.
Run golden-file tests when upgrading MongoDB drivers or Spring Data BOM.

When ERROR becomes FIXED, you usually changed one of: query type (string → UUID), subtype (03 → 04), or driver codec defaults - not the business logic. Keep a short postmortem vector in your repo so the next team does not repeat the same Compass copy-paste trap.

FAQ

Why does Compass show a UUID but my Node query fails?: Compass renders Binary with a friendly UUID view. Your query may use a string, wrong subtype, or a permuted byte order. Match the BSON type and subtype your documents actually store.
Is Invalid UUID format always a typo?: Often it is format or type mismatch - hyphens, braces, hex length - or using string operators on binary fields. Less often it is truly random bytes labeled as UUID.
Can I fix encoding without downtime?: Reads can be fixed with correct codecs immediately. Changing stored subtype or string→binary on _id usually needs a planned migration because _id bytes may change.
Should APIs accept UUID as string or binary?: Public APIs typically accept canonical strings and convert once at the boundary to BSON UUID subtype 04. Never accept multiple string formats without normalization.

Browse all tools