55P04 — unsafe_new_enum_value_usage
55P04 protects the commit-before-use rule for a newly added enum value. It is raised after PostgreSQL has found an enum tuple that is still uncommitted and marked as unsafe, not because the label has invalid syntax.
English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.
Reading PG 18·Select a recorded version
- aliases
- Unknown
- class name
- Object Not In Prerequisite State
- condition name
- unsafe_new_enum_value_usage
- lang
- en
- sqlstate
- 55P04
Definition PG 18
55P04
At a glance {#at-a-glance}
55P04 protects the commit-before-use rule for a newly added enum value. It is raised after PostgreSQL has found an enum tuple that is still uncommitted and marked as unsafe, not because the label has invalid syntax.
Meaning {#meaning}
The fixed enum.c guard first accepts a tuple already hinted committed, then checks the tuple's transaction ID. It also accepts a value not listed by EnumUncommitted(), because such a value cannot outlive its owning type. Only the remaining uncommitted value is rejected with the exact primary, detail, and hint below. Thus an ALTER TYPE ... ADD VALUE and a use of that new label in one uncommitted transaction can reach 55P04, while an already committed label does not.
Messages {#messages}
- Primary template:
unsafe use of new value "%s" of enum type %s - Detail: none in this call group.
- Hint:
New enum values must be committed before they can be used.
The %s values are the enum label and formatted enum type name from the tuple; they are diagnostic data, not a value-format recipe.
Diagnosis {#diagnosis}
Preserve the enum label, type name, SQLSTATE, severity, and transaction status. Check whether the value was added earlier in the same still-open transaction and whether the failed use is an enum input/cast or another expression that resolves the enum value. Distinguish this guard from an invalid enum label (22P02); 22P04 is a COPY file-format condition, not this enum guard. Also distinguish a duplicate ADD VALUE operation.
Response {#response}
First recover the transaction after the ERROR: issue ROLLBACK, or use an appropriate ROLLBACK TO SAVEPOINT when the savepoint was placed so the earlier ADD VALUE remains. Do not use the label while the addition is still uncommitted. If a full rollback or savepoint rollback discarded the ADD VALUE, issue it again in a new transaction and COMMIT; if a savepoint preserved it, commit that transaction before using the label. Then start or continue a transaction that can see the committed catalog row. In autocommit, fix the commit boundary and retry the input; do not retry the same uncommitted sequence.
Versions {#versions}
The locked catalogue records this condition from 12.0; fixed source coverage is PostgreSQL 18.6. The catalogue boundary does not assert that the guard had no earlier private or unresolved form.
Related {#related}
Sources {#sources}
src/backend/utils/adt/enum.c#L68-102
The structured evidence record records the exact guard and message group; no natural runtime case is claimed.
Compare versions
SQLSTATE evidence and recorded runtime versions
claims · identity
{
"claim_id": "identity",
"limits": "",
"method": "Read fixed definition.",
"position": 0,
"runtime": [],
"sources": [
"src.errcodes.18.6"
],
"statement": "55P04 is unsafe_new_enum_value_usage in SQLSTATE Class 55."
}claims · resolved-paths
{
"claim_id": "resolved-paths",
"limits": "Source confirmation is not natural runtime.",
"method": "Read complete fixed source context.",
"position": 1,
"runtime": [],
"sources": [
"src.path.0"
],
"statement": "The fixed enum tuple commit and EnumUncommitted guards support the stated commit-before-use mechanism and message."
}claims · history
{
"claim_id": "history",
"limits": "",
"method": "Use catalogue boundary.",
"position": 2,
"runtime": [],
"sources": [
"src.errcodes.18.6"
],
"statement": "The locked catalogue records 55P04 from 12.0; that boundary does not prove exact implementation introduction."
}messages · message.0
{
"limits": "",
"message_id": "message.0",
"path": "",
"position": 0,
"raw": {
"hint_template": "New enum values must be committed before they can be used.",
"id": "message.0",
"primary_template": "unsafe use of new value \"%s\" of enum type %s",
"severity_source": "ERROR",
"sources": [
"src.path.0"
],
"sqlstate": "55P04"
},
"severity": "ERROR",
"sources": [
"src.path.0"
],
"templates": [
{
"kind": "primary",
"literal": "unsafe use of new value \" \" of enum type",
"position": 0,
"role": "",
"template": "unsafe use of new value \"%s\" of enum type %s"
},
{
"kind": "hint",
"literal": "New enum values must be committed before they can be used.",
"position": 1,
"role": "",
"template": "New enum values must be committed before they can be used."
}
]
}sources · src.errcodes.18.6
{
"commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
"docs_url": "",
"kind": "upstream_source",
"location": "",
"path": "src/backend/utils/errcodes.txt",
"position": 0,
"sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
"source_id": "src.errcodes.18.6",
"tag": "REL_18_6",
"url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L428"
}sources · src.path.0
{
"commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
"docs_url": "",
"kind": "upstream_source",
"location": "",
"path": "src/backend/utils/adt/enum.c",
"position": 1,
"sha256": "35c0f1f5376a5c2ef3d7ea52fa26faad84b493b485ed3a9ad5bb5b5eb45928b2",
"source_id": "src.path.0",
"tag": "REL_18_6",
"url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/enum.c#L68"
}Source references
Full definition and evidence JSON
Definition sources
center · PostgreSQL 18 · english-manuals:746a28d1b80c46fde5495338e98da7761a6b4b28687c9c5e41b6a14f698e70b9
Text language: en · english-manuals:746a28d1b80c46fde5495338e98da7761a6b4b28687c9c5e41b6a14f698e70b9