Nil UUID

Definition

The nil UUID is a special UUID with all 128 bits set to zero:

00000000-0000-0000-0000-000000000000

RFC 9562 defines the nil UUID as a reserved value that represents the absence of a UUID. It is the UUID equivalent of null, None, nil, or 0 in other data types — a sentinel that means “no UUID assigned here.”

When to use the nil UUID

Use the nil UUID when:

• An API field is optional — returning 00000000-0000-0000-0000-000000000000 is more explicit than returning null and avoids null pointer issues in strictly-typed languages
• A record has not been assigned an ID yet — a pre-creation state that needs a valid UUID-typed placeholder
• Default/zero value semantics — many UUID libraries use the nil UUID as the zero value of the UUID type (e.g., Go’s uuid.UUID{}, .NET’s Guid.Empty)
• Filtering — using nil as a sentinel in a query to mean “any” or “unset”

Language support

Go

import "github.com/google/uuid"

var id uuid.UUID // zero value = nil UUID
fmt.Println(id == uuid.Nil) // true
fmt.Println(id)             // 00000000-0000-0000-0000-000000000000

.NET / C#

Guid id = Guid.Empty;
Console.WriteLine(id == Guid.Empty); // true
Console.WriteLine(id); // 00000000-0000-0000-0000-000000000000

Python

import uuid

nil = uuid.UUID(int=0)
print(nil)             # 00000000-0000-0000-0000-000000000000
print(nil == uuid.UUID('00000000-0000-0000-0000-000000000000'))  # True

JavaScript / TypeScript

There is no built-in nil UUID constant in JavaScript. The common pattern is a module-level constant:

export const NIL_UUID = '00000000-0000-0000-0000-000000000000';

// Or use the uuid package:
import { NIL } from 'uuid';
console.log(NIL); // '00000000-0000-0000-0000-000000000000'

Database considerations

When storing UUIDs in a database, avoid using the nil UUID as a foreign key value — it creates an implicit coupling between the nil sentinel and any record with that UUID. Instead:

• Use a nullable UUID column (uuid NULL) and store NULL for “no reference”
• Reserve the nil UUID for truly universal “absent” semantics, not as a foreign key

PostgreSQL example:

CREATE TABLE events (
  id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  parent_id  uuid NULL  -- NULL means no parent, not nil UUID
);

Nil UUID is not a valid identifier

The nil UUID should never be used as a real identifier for a record, user, or resource. Because it is the zero value in most UUID implementations, it will appear in uninitialized data and default struct fields. Using it as a real ID creates ambiguity between “this record has no ID” and “this is record zero.”

Max UUID

RFC 9562 also defines the max UUID: ffffffff-ffff-ffff-ffff-ffffffffffff — all bits set to one. It serves the same sentinel role at the other end of the ordering range and is useful as an upper bound in range queries on UUID v7 values.

Related terms

• UUID — the full identifier definition
• Collision — why two generated UUIDs being equal is effectively impossible
• Entropy — the randomness that fills all non-structural bits in real UUIDs

Generate a real UUID with the UUID v7 generator or UUID v4 generator.