PostgreSQL error 55P04: unsafe_new_enum_value_usage

What does unsafe_new_enum_value_usage mean?

PostgreSQL error 55P04 signals that a new ENUM label is being used before the database guarantees its visibility and correct sort order. The server blocks the statement to prevent catalog corruption and inconsistent query results.

By design, ALTER TYPE ... ADD VALUE runs as a catalog update.

If the same transaction later inserts, updates or alters data using that label, PostgreSQL raises 55P04 to force you to commit first.

When does error 55P04 occur?

The error surfaces inside a single transaction or function that both adds the ENUM label and uses it. It often appears in migration scripts, psql \\i files, or ORMs that batch DDL and DML together.

Error frequency increases in automated CI pipelines where multiple steps run under BEGIN ...

COMMIT wrappers, hiding transactional boundaries from engineers.

Why is it important to fix quickly?

Continuing with unsafe usage could let concurrent backends read an ENUM before its ordering metadata is stable.

PostgreSQL blocks the action, so your transaction fails entirely until corrected, halting deployments and application writes.

Rapid remediation keeps release pipelines green and prevents downtime caused by incomplete schema changes.

What Causes This Error?

The primary trigger is executing INSERT, UPDATE, or DEFAULT clauses that reference the new ENUM value in the same transaction as ALTER TYPE ...

ADD VALUE.

Additional causes include PL/pgSQL functions that call both statements, ORMs that wrap migrations in a transaction, and psql scripts containing an implicit BEGIN.

How to Fix unsafe_new_enum_value_usage

Split the DDL and DML into separate transactions. First add the ENUM value, commit, then run inserts or updates.

This guarantees catalog safety.

Disable transaction wrapping in your migration tool, or add explicit COMMIT statements between the ALTER TYPE and any data-modification statements.

Common Scenarios and Solutions

CI pipeline migration - Add a second migration file or step that only contains data updates.

psql script - Insert a COMMIT after the ALTER TYPE command.

PL/pgSQL function - Unpack the logic into two separate function calls executed sequentially.

Best Practices to Avoid This Error

Add new ENUM values in isolated migrations and commit them before deploying application code that references the value.

Avoid long-running transactions that bundle unrelated DDL and DML.

Use feature flags or default mappings until the new value exists cluster-wide.

Galaxy’s editor highlights DDL inside large transactions and warns when subsequent statements reference freshly added ENUM labels, helping you commit at the right boundary.

Related Errors and Solutions

42710 duplicate_object - Adding an ENUM label that already exists. Solve by checking pg_type first or using IF NOT EXISTS in PostgreSQL 15+.

42804 datatype_mismatch - Inserting a string not declared as an ENUM label.

Add the label or cast properly.

55006 object_in_use - Trying to drop an ENUM used in a table. Remove dependencies or cascade.

.