# 55P02 — cant_change_runtime_param

> PostgreSQL SQLSTATE 55P02 的来源与诊断参考。
---

# 55P02

## 速览 {#at-a-glance}

`55P02` 表示 PostgreSQL 因 GUC 上下文或服务器生命周期阶段不允许，而拒绝修改运行时参数。同一条件名覆盖只能重启、只能 SIGHUP、只能在 backend 启动时、内部参数以及 binary-upgrade guard 等路径。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `55P02` |
| 条件名 | `cant_change_runtime_param` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `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` |
| 宏 | `ERRCODE_CANT_CHANGE_RUNTIME_PARAM` |
| 别名 | `—` |

<!-- source facts: data/errcodes/55P02.json -->
<!-- END SQLSTATE FACTS -->

## 含义 {#meaning}

`set_config_with_handle()` 使用 `ereport(elevel, ...)`，所以客户端看到的 severity 取决于调用者：SQL `SET` 通常使用 `ERROR`，配置文件、数据库/角色设置等路径可能使用 `LOG` 或 `WARNING`。源码先检查 GUC context：内部参数不能由普通调用者修改；`PGC_POSTMASTER` 参数需要重启；`PGC_SIGHUP` 参数在 session 中修改会报 `parameter "%s" cannot be changed now`；backend 或 superuser-backend 参数在连接启动后修改会报 `parameter "%s" cannot be set after connection start`。重启提示也用于重载时试图改变 postmaster 参数的情形，`ALTER SYSTEM` 还会拒绝不能写入其配置文件的参数。

`pg_upgrade_support.c` 另有 binary-upgrade guard：`IsBinaryUpgrade` 为假时，升级辅助函数报此码。这是内部管理前置条件，不是普通 `pg_settings.context` 判断。

## 消息 {#messages}

- 内部参数或配置文件拒绝：primary 为 `parameter "%s" cannot be changed`；`set_config_with_handle()` 的调用者提供 severity，而 `ALTER SYSTEM` guard 使用 ERROR。
- 只能重启的参数：primary 为 `parameter "%s" cannot be changed without restarting the server`；severity 由调用者提供。
- 在 session 中修改 SIGHUP 参数：primary 为 `parameter "%s" cannot be changed now`；severity 由调用者提供。
- 连接启动后修改 backend 参数：primary 为 `parameter "%s" cannot be set after connection start`；severity 由调用者提供。
- binary-upgrade 模式外调用升级 helper：primary 为 `function can only be called when server is in binary upgrade mode`，ERROR。

## 诊断 {#diagnosis}

记录参数名、完整 primary message、设置来源（`SET`、启动选项、配置重载、数据库/角色设置、`ALTER SYSTEM` 或 binary-upgrade helper）及服务器阶段。检查 `pg_settings.context`、`pending_restart`、`source` 和 `sourcefile`：`postmaster` 指向重启，`sighup` 指向 reload，`backend` 指向新连接。值格式错误属于其他 SQLSTATE，不能只凭 `55P02` 判断。

用户发出的 `SET` 若以 `ERROR` 失败，会使显式事务进入错误状态；配置重载或后台路径可能只记录日志或发 WARNING，并不等于客户端事务被回滚，要以实际 severity 和连接状态为准。

## 处理 {#response}

按 `pg_settings` 指示的上下文修改：只能重启的值写入配置后重启，SIGHUP 值执行 reload，backend 值在新 session 中设置，内部或 binary-upgrade 参数交给所属机制。显式事务中的 SQL `SET` 失败后，先执行 `ROLLBACK` 或 `ROLLBACK TO SAVEPOINT`，再继续发送命令。autocommit 下先修正生命周期或设置来源，再重试；不要盲目重复同一被拒绝的操作。转换完成后核对实际生效值。

## 版本 {#versions}

锁定目录从 7.4 记录此条件；固定源码覆盖 PostgreSQL 18.6。`已知存在于` 是目录边界，不等于精确实现引入版本。

## 相关 {#related}

[`55P03`](../55p03/)、[`57P03`](../57p03/)、[`42501`](../42501/)

## 来源 {#sources}

[src/backend/utils/misc/guc.c#L3407-3428](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3407)

[src/backend/utils/misc/guc.c#L3477-3512](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3477)

[src/backend/utils/misc/guc.c#L3550-3581](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L3550)

[src/backend/utils/adt/pg_upgrade_support.c#L32-39](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/pg_upgrade_support.c#L32)

[src/backend/utils/misc/guc.c#L4691-4694](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/misc/guc.c#L4691)

结构化[证据记录](../../data/evidence/55p02.json)保存固定消息、调用者 severity 边界以及源码/运行范围。