55P02

At a glance

55P02 means that PostgreSQL rejected a runtime-parameter change because the GUC context or lifecycle phase does not permit that operation. The same condition name covers restart-only, SIGHUP-only, backend-start, internal, and binary-upgrade guards.

Meaning

set_config_with_handle() calls ereport(elevel, ...), so the client-visible severity follows the caller: a SQL SET normally uses ERROR, while configuration-file/database-setting paths may use LOG or WARNING. The guard first checks the GUC context. Internal parameters cannot be changed by an ordinary caller; PGC_POSTMASTER parameters require a restart; PGC_SIGHUP parameters reject a session-only change with parameter "%s" cannot be changed now; and backend or superuser-backend parameters reject a late change with parameter "%s" cannot be set after connection start. The same restart message is also used when a reload would change a postmaster value, and ALTER SYSTEM rejects parameters that cannot be placed in its configuration file.

A separate pg_upgrade_support.c guard uses this SQLSTATE when a binary-upgrade helper is called while IsBinaryUpgrade is false. That path is an internal administrative precondition, not a regular pg_settings.context decision.

Messages

• Internal or configuration-file rejection: primary parameter "%s" cannot be changed; the set_config_with_handle() caller supplies the severity, while the ALTER SYSTEM guard uses ERROR.
• Restart-only parameter: primary parameter "%s" cannot be changed without restarting the server; the caller supplies the severity.
• SIGHUP-only parameter changed in a session: primary parameter "%s" cannot be changed now; the caller supplies the severity.
• Backend-start parameter changed after connection start: primary parameter "%s" cannot be set after connection start; the caller supplies the severity.
• Binary-upgrade helper outside binary-upgrade mode: primary function can only be called when server is in binary upgrade mode, ERROR.

Diagnosis

Record the parameter name, exact primary message, source (SET, startup option, configuration reload, database/role setting, ALTER SYSTEM, or binary-upgrade helper), and the server phase. Check pg_settings.context, pg_settings.pending_restart, pg_settings.source, and pg_settings.sourcefile; a postmaster context points to restart, sighup to reload, and backend to a new session. A value-format problem has a different SQLSTATE and should not be diagnosed from 55P02.

For a user SET, an ERROR aborts the current explicit transaction. For a configuration reload or background path, the same format may be logged or reported as a warning and does not imply a client transaction was aborted; use the reported severity and connection state.

Response

Apply the change through the context named by pg_settings: use configuration and restart for restart-only values, reload SIGHUP values, pass backend-start values through a new connection, and leave internal or binary-upgrade-only parameters to their owning mechanism. In an explicit transaction, issue ROLLBACK or ROLLBACK TO SAVEPOINT after a failed SQL SET before sending further commands. In autocommit, correct the lifecycle or source first and retry the setting; do not blindly repeat the same rejected operation. Confirm the effective value after the transition.

Versions

The locked catalogue records this condition from 7.4; fixed source coverage is PostgreSQL 18.6. The known present by value is a catalogue boundary, not an exact implementation-introduction claim.

Related

55P03, 57P03, 42501

Sources

src/backend/utils/misc/guc.c#L3407-3428

src/backend/utils/misc/guc.c#L3477-3512

src/backend/utils/misc/guc.c#L3550-3581

src/backend/utils/adt/pg_upgrade_support.c#L32-39

src/backend/utils/misc/guc.c#L4691-4694

The structured evidence record records fixed messages, caller-severity boundaries, and the source/runtime scope.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/misc/guc.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/misc/guc.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/misc/guc.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/adt/pg_upgrade_support.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/misc/guc.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7

Message templates

parameter "%s" cannot be changed without restarting the server

parameter "%s" cannot be changed now

parameter "%s" cannot be set after connection start

parameter "%s" cannot be changed

function can only be called when server is in binary upgrade mode

Reproduction & repair cases

No reproduction case is attached to this condition.

Recorded runtime evidence

No runtime observation is attached to this entry.