Postgres "operator does not exist: uuid = text": the driver change that turned your UUIDs into strings

verbatim errorERROR: operator does not exist: uuid = text LINE 2: WHERE id = $1 HINT: No operator matches the given name and argument types. You might need to add explicit type casts.

Problem

After migrating a service from one Postgres client to another (pg → postgres.js), every query filtering on a UUID column failed:

ERROR: operator does not exist: uuid = text
LINE 2: WHERE id = $1
HINT: No operator matches the given name and argument types. You might need to add explicit type casts.

The code did not change — WHERE id = $1 with a string parameter worked for two years with the old driver.

Root cause

Postgres is strict about types, and the error is literal: the left side is uuid, the right side arrived as text, and no uuid = text operator exists in core Postgres. The old driver silently typed untyped string parameters as uuid (or the server-side prepare inferred it); the new one sends plain text and lets Postgres reject it. Same wire behavior, different parameter typing defaults.

🔒 the fix — including 4 code blocks — is members-only. $1/mo unlocks everything.