Uuid Toolkit

Collision-Free UUIDs in a Multi-Tenant FHIR Deployment

UUID collisions are theoretically possible and effectively impossible with a properly-generated v4 across every FHIR workload short of the entire industry writing to one namespace. The real problem in multi-tenant deployments is not the birthday paradox — it is the operational patterns that turn a "one per resource" id into "many per resource" or "same across tenants." Those patterns are preventable with a small set of rules. The site's fullUrl UUID spinner produces the raw ids; the operational discipline lives around them. For the wider FHIR framing, the rest of our FHIR reviews has more.

The Birthday Paradox In Real Terms

A properly-generated v4 UUID has 122 bits of entropy. To hit a 50% collision probability, you would need to generate roughly 2^61 UUIDs. That is roughly 2.3 × 10^18 ids. No FHIR deployment reaches that scale.

If you are worried about entropy-based collisions with a properly-seeded RNG, you are worrying about the wrong thing.

The Operational Patterns That Cause Real Collisions

  • Same seed across nodes — deterministic "random" that repeats
  • Copying a database between environments without id remapping
  • Backup-restore across tenants without id namespacing
  • Test fixtures using hard-coded UUIDs that end up in production
  • Poorly-seeded RNGs on containers with identical entropy states

Each of these is a real, preventable engineering mistake. Each shows up in incident postmortems more than actual entropy collisions do.

Isolate Test Fixtures

Test data should never share UUIDs with production. The pattern that catches this:

  • Reserve a distinct prefix or well-known set of UUIDs for tests
  • Verify no test UUID is present in production
  • Fail-close in production if a test-reserved UUID appears

That is a small cost and catches an ugly class of incident.

For the environment-stability side, keeping UUIDs stable across environments is the entry.

Container Entropy

Containers spun up with identical initial state on the same host can share a poorly-seeded RNG for a brief window. Every serious container runtime addresses this, but bespoke images may not.

Verify:

  • /dev/urandom is available and reads produce varying data
  • The UUID library uses a cryptographic RNG, not a PRNG
  • Container startup does not race the seeding of the RNG

Once verified, the risk drops back to birthday-paradox levels — that is, negligible.

Tenant Namespacing In Storage

Even with unique UUIDs, tenant-scoped storage should key on tenant + UUID, not just UUID. That catches cross-tenant leakage regardless of id uniqueness.

For the v4 vs v7 discussion, UUID v4 vs v7: is the tradeoff meaningful for FHIR? is the entry.

Database-Level Uniqueness Constraints

  • UNIQUE(resource_type, id) per tenant
  • Optional cross-tenant uniqueness for shared namespaces

Unique constraints catch the operational mistakes even when your code does not.

Migration From Backup

Copying a tenant's data into a different tenant's environment (for testing, staging, or migration) requires id remapping. Skipping the remap produces cross-tenant collisions immediately.

For the migration side, UUID hygiene for teams migrating from sequential IDs covers the pattern.

Where UUIDs Get Generated

Edge generation is safer for cross-tenant isolation because the client's context is tenant-scoped. Server generation centralizes control. For the trade-off, generating UUIDs at the edge vs at the server is the entry.

The Short Version

Entropy collisions are effectively impossible with proper v4. Operational collisions are the real risk. Isolate tests, verify container entropy, namespace by tenant in storage, enforce uniqueness constraints, remap on migration. That is the collision-free playbook.

Halftone-comic diagram of operational sources of UUID collision — test fixtures, container entropy, backup migration, cross-tenant copy — with prevention rules annotated, with dot pattern shading and hot-pink accents on cream paper

Sources