55P02 — cant_change_runtime_param

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.

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

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Object Not In Prerequisite State
condition name: cant_change_runtime_param
lang: en
sqlstate: 55P02

Definition PG 18

55P02

At a glance {#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 {#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 {#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 {#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 {#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 {#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 {#related}

55P03, 57P03, 42501

Sources {#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.

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": "55P02 is cant_change_runtime_param in SQLSTATE Class 55."
}

claims · resolved-paths

{
  "claim_id": "resolved-paths",
  "limits": "Source confirmation is not natural runtime.",
  "method": "Read complete fixed source contexts.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.path.1",
    "src.path.2",
    "src.path.3",
    "src.path.4"
  ],
  "statement": "The fixed GUC context guards, caller severity selection, ALTER SYSTEM guard, and binary-upgrade guard support the mechanisms described."
}

claims · severity-boundary

{
  "claim_id": "severity-boundary",
  "limits": "",
  "method": "Read set_config_with_handle severity selection.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.0"
  ],
  "statement": "The same report group uses caller-supplied elevel: SQL settings normally reach ERROR, while file/database/role sources can use LOG or WARNING."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 55P02 from 7.4; that boundary does not prove exact implementation introduction."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.0",
    "primary_template": "parameter \"%s\" cannot be changed without restarting the server",
    "severity_source": "caller-supplied elevel (normally ERROR for SQL SET; LOG/WARNING possible for configuration sources)",
    "sources": [
      "src.path.1",
      "src.path.4"
    ],
    "sqlstate": "55P02"
  },
  "severity": "caller-supplied elevel (normally ERROR for SQL SET; LOG/WARNING possible for configuration sources)",
  "sources": [
    "src.path.1",
    "src.path.4"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "parameter \" \" cannot be changed without restarting the server",
      "position": 0,
      "role": "",
      "template": "parameter \"%s\" cannot be changed without restarting the server"
    }
  ]
}

messages · message.1

{
  "limits": "",
  "message_id": "message.1",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.1",
    "primary_template": "parameter \"%s\" cannot be changed now",
    "severity_source": "caller-supplied elevel",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "55P02"
  },
  "severity": "caller-supplied elevel",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "parameter \" \" cannot be changed now",
      "position": 0,
      "role": "",
      "template": "parameter \"%s\" cannot be changed now"
    }
  ]
}

messages · message.2

{
  "limits": "",
  "message_id": "message.2",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.2",
    "primary_template": "parameter \"%s\" cannot be set after connection start",
    "severity_source": "caller-supplied elevel",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "55P02"
  },
  "severity": "caller-supplied elevel",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "parameter \" \" cannot be set after connection start",
      "position": 0,
      "role": "",
      "template": "parameter \"%s\" cannot be set after connection start"
    }
  ]
}

messages · message.3

{
  "limits": "",
  "message_id": "message.3",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.3",
    "primary_template": "parameter \"%s\" cannot be changed",
    "severity_source": "ERROR",
    "sources": [
      "src.path.3",
      "src.path.4"
    ],
    "sqlstate": "55P02"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.3",
    "src.path.4"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "parameter \" \" cannot be changed",
      "position": 0,
      "role": "",
      "template": "parameter \"%s\" cannot be changed"
    }
  ]
}

messages · message.4

{
  "limits": "",
  "message_id": "message.4",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.4",
    "primary_template": "function can only be called when server is in binary upgrade mode",
    "severity_source": "ERROR",
    "sources": [
      "src.path.3"
    ],
    "sqlstate": "55P02"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.3"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "function can only be called when server is in binary upgrade mode",
      "position": 0,
      "role": "",
      "template": "function can only be called when server is in binary upgrade mode"
    }
  ]
}

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#L426"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/misc/guc.c",
  "position": 1,
  "sha256": "3021d40bb4e920a56fbc5e9452e32903a7364d7ce0aece65be70aa3c34c1274e",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3407"
}

sources · src.path.1

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/misc/guc.c",
  "position": 2,
  "sha256": "3021d40bb4e920a56fbc5e9452e32903a7364d7ce0aece65be70aa3c34c1274e",
  "source_id": "src.path.1",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3477"
}

sources · src.path.2

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/misc/guc.c",
  "position": 3,
  "sha256": "3021d40bb4e920a56fbc5e9452e32903a7364d7ce0aece65be70aa3c34c1274e",
  "source_id": "src.path.2",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3550"
}

sources · src.path.3

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/pg_upgrade_support.c",
  "position": 4,
  "sha256": "c9b9bfb233db85f0b8029f791d6cf39f6c479c3f7274dc2d7af0b79fbfbbd4ad",
  "source_id": "src.path.3",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/pg_upgrade_support.c#L32"
}

sources · src.path.4

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/misc/guc.c",
  "position": 5,
  "sha256": "3021d40bb4e920a56fbc5e9452e32903a7364d7ce0aece65be70aa3c34c1274e",
  "source_id": "src.path.4",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L4691"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:56bd35593eed8aa40b6c084ee9477d59653df7b84d394c4c70dd1cf0fcd8e463

Text language: en · english-manuals:56bd35593eed8aa40b6c084ee9477d59653df7b84d394c4c70dd1cf0fcd8e463