55P02 — cant_change_runtime_param

Source-backed reference for PostgreSQL SQLSTATE 55P02.

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.

Field	Value
SQLSTATE	`55P02`
Condition	`cant_change_runtime_param`
Status	`active`
Known present by	`7.4`
Locked snapshots	`9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3`
Macros	`ERRCODE_CANT_CHANGE_RUNTIME_PARAM`
Aliases	`—`

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.

55P03, 57P03, 42501