PostgreSQL Cannot Change Runtime Parameter (SQLSTATE 55P02)

When you attempt to change a configuration parameter that PostgreSQL only allows to be set at server startup, PostgreSQL raises:

ERROR:  parameter "max_connections" cannot be changed without restarting the server
SQLSTATE: 55P02

The SQLSTATE code is 55P02 and the condition name is cant_change_runtime_param. This error belongs to error class 55 ("Object Not In Prerequisite State") and indicates that the requested configuration change is not permitted at runtime.

What This Error Means

PostgreSQL configuration parameters are divided into several context categories that determine when and how they can be changed. The cant_change_runtime_param error fires when you issue a SET command (or use ALTER SYSTEM SET, ALTER DATABASE SET, or ALTER ROLE SET) for a parameter whose context is postmaster — meaning PostgreSQL requires a full server restart to apply the change.

Parameters in the postmaster context affect fundamental aspects of how PostgreSQL allocates resources at startup, such as shared memory segments, the number of allowed connections, or the size of internal data structures. Because these resources are allocated once when the postmaster process starts, PostgreSQL cannot safely change them while the server is running.

This is distinct from parameters in the sighup context (reloadable without restart via pg_reload_conf() or SELECT pg_reload_conf()), and from user- or superuser-context parameters that individual sessions can change freely with SET. When a SET or ALTER SYSTEM command targets a postmaster-context parameter in a running session, error 55P02 is raised and the command has no effect.

Common Causes

1. Calling SET on a postmaster-only parameter in a session. Parameters like max_connections, shared_buffers, wal_level, max_wal_senders, listen_addresses, and port are set at startup and cannot be changed by SET in a live session.

2. Using ALTER SYSTEM SET and expecting immediate effect. ALTER SYSTEM SET writes to postgresql.auto.conf, but for postmaster-context parameters the new value takes effect only after a server restart — trying to apply the change without restarting will not raise this error in itself, but any session-level SET for the same parameter will.

3. Automation or migration scripts that issue SET commands copied from postgresql.conf examples. Scripts may blindly issue SET for every parameter they find in a configuration template, including those that only belong in postgresql.conf and require a restart.

4. Application startup code setting parameters via the connection string or SET immediately after connecting. If the parameter is postmaster-context, the SET will fail, which can abort the connection setup entirely depending on the driver.

How to Fix cant_change_runtime_param

1. Identify the parameter's context. Check what context a given parameter belongs to by querying pg_settings:

   SELECT name, context, setting, unit
   FROM pg_settings
   WHERE name = 'max_connections';
   

   If context is postmaster, the parameter requires a server restart. If it is sighup, you can reload the configuration without restarting.

2. Edit postgresql.conf (or postgresql.auto.conf) and restart the server. For postmaster-context parameters, the correct workflow is to update the configuration file and then restart:

   # Edit postgresql.conf
   sudo nano /etc/postgresql/16/main/postgresql.conf
   # Change the parameter value, then restart
   sudo systemctl restart postgresql
   

   Or using ALTER SYSTEM followed by a restart:

   ALTER SYSTEM SET max_connections = 200;
   -- Changes are staged in postgresql.auto.conf
   -- A server restart is required before the new value takes effect
   

3. Use pg_reload_conf() for sighup-context parameters instead. If the parameter is sighup-context (not postmaster), you do not need a restart — update the file and reload:

   SELECT pg_reload_conf();
   

4. Remove the offending SET from your application or migration script. If SET statements for startup-only parameters are in application connection strings or initialization code, remove them. These parameters cannot be controlled per-session regardless.

5. Check current and pending values. After using ALTER SYSTEM, you can confirm the pending value and whether a restart is needed:

   SELECT name, setting, pending_restart
   FROM pg_settings
   WHERE pending_restart = true;
   

   A true in pending_restart means the value in postgresql.auto.conf differs from the live value and a restart is required.

Additional Information

• Error class 55 ("Object Not In Prerequisite State") groups errors where the database object or server is not in the right state for the requested operation. Sibling conditions include 55000 (object_not_in_prerequisite_state) and 55006 (object_in_use).
• The distinction between postmaster, sighup, superuser, user, and backend parameter contexts has been present since early versions of PostgreSQL and is well-documented in the PostgreSQL documentation on GUC parameters.
• Most PostgreSQL client drivers (libpq, JDBC, psycopg2, etc.) surface this as a server-side error with the SQLSTATE 55P02. Some ORMs that run a SET block at connection time (e.g., Django with options in DATABASES) will raise a connection initialization error if a postmaster-context parameter is included.
• Cloud-managed PostgreSQL services (Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL) expose startup-only parameters through their own parameter group or flag UI. Attempting to change them via SQL SET will still raise 55P02; use the cloud console or CLI instead, then trigger an instance restart through the service.

Frequently Asked Questions

Why does ALTER SYSTEM SET max_connections = 200 not raise an error, but SET max_connections = 200 does?

ALTER SYSTEM SET only writes a value to postgresql.auto.conf on disk — it does not apply the change to the running server. PostgreSQL accepts the write without error but marks the parameter as pending_restart = true. The SET command, on the other hand, tries to apply the value to the live server immediately, which is not possible for postmaster-context parameters, so it raises 55P02.

How do I tell which parameters need a restart vs. a reload?

Query pg_settings and filter by context:

SELECT name, context, setting
FROM pg_settings
WHERE context = 'postmaster'
ORDER BY name;

Parameters with context = 'sighup' can be applied with SELECT pg_reload_conf() after editing the config file; those with context = 'postmaster' require a full server restart.

Can I change max_connections without any downtime?

No. max_connections is a postmaster-context parameter that determines the size of shared memory structures allocated at startup. A server restart is required. In high-availability setups (e.g., Patroni, repmgr), you can perform a rolling restart of replicas first, then promote and restart the primary, to minimize downtime.

Why does this error sometimes abort my entire transaction?

PostgreSQL's error handling aborts the current transaction on any error unless you are using subtransactions (SAVEPOINT). If the SET command raising 55P02 is inside an explicit transaction block, the transaction enters an aborted state and all subsequent commands will fail until you issue ROLLBACK. Issue the SET outside of a transaction block, or remove it entirely if the parameter is not settable at runtime.