How to fix Parameter requires restart in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 28, 2025· 224 views

PostgreSQL parameters with "postmaster" context cannot be changed without restarting the server. Learn how to identify restart-required parameters, apply changes correctly, and verify pending restarts.

Quick fix

Fixes Parameter requires restart

SELECT name, context, setting
FROM pg_catalog.pg_settings
WHERE context = 'postmaster'
ORDER BY name;
  1. Identify which parameters require restart
  2. Check for pending restart changes
  3. Apply the configuration change
  4. Restart PostgreSQL to apply the change
postgresql — error
SELECT name, context, setting
FROM pg_catalog.pg_settings
WHERE context = 'postmaster'
ORDER BY name;
Parameter requires restart

What this error means

When PostgreSQL displays "Parameter requires restart," it means you attempted to change a configuration setting that requires a full server restart to take effect. PostgreSQL has different parameter contexts: postmaster parameters require a restart, SIGHUP parameters only need a reload, and user/session parameters can be changed immediately. Postmaster parameters typically control core server resources like memory allocation, connection limits, and protocol settings that cannot be modified while the server is running.

Typical symptoms

  • Error message "parameter X cannot be changed without restarting the server" when using ALTER SYSTEM or modifying postgresql.conf
  • Changes to shared_buffers, max_connections, port, or listen_addresses are not applied after reload
  • pg_pending_restart column shows true for changed parameters in pg_settings view
  • Configuration changes written to postgresql.auto.conf but not taking effect
  • Need to restart PostgreSQL for changes to critical parameters to apply

Common causes

  1. Attempting to change postmaster-context parameters without restarting the server
  2. Using ALTER SYSTEM or postgresql.conf to modify server resource parameters that require restart
  3. Confusing reload (which only applies SIGHUP parameters) with restart (needed for postmaster parameters)
  4. Not checking the context column in pg_settings before making configuration changes
  5. Unaware which parameters require restart versus which can be reloaded

How to fix "Parameter requires restart"

1Identify which parameters require restart

Query the pg_settings system view to see all parameters that require restart:

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

Parameters with context "postmaster" require a full restart. Parameters with context "sighup" only need a reload with SELECT pg_reload_conf().

2Check for pending restart changes

After making changes with ALTER SYSTEM or modifying postgresql.conf, check if a restart is pending:

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

If any rows are returned, a server restart is required for those settings to take effect.

3Apply the configuration change

There are two ways to change parameters:

Using ALTER SYSTEM (recommended):

sql
ALTER SYSTEM SET parameter_name = value;

Or edit postgresql.conf directly:

bash
sudo nano /etc/postgresql/16/main/postgresql.conf

Changes made with ALTER SYSTEM are written to postgresql.auto.conf, not postgresql.conf.

4Restart PostgreSQL to apply the change

For postmaster parameters, restart the entire PostgreSQL server:

On Linux (systemd):

bash
sudo systemctl restart postgresql

On macOS (if installed via Homebrew):

bash
brew services restart postgresql

Using pg_ctl:

bash
sudo -u postgres /usr/lib/postgresql/16/bin/pg_ctl -D /var/lib/postgresql/16/main restart
5Verify the parameter change took effect

After restart, verify the new value is applied:

sql
SELECT name, setting, pending_restart
FROM pg_settings
WHERE name = 'your_parameter_name';

Confirm that pending_restart is now false and the setting matches your intended value.

Advanced notes

Common postmaster parameters that cause this error: shared_buffers (memory for caching), max_connections (connection limit), wal_level (write-ahead logging level), listen_addresses (network binding), port (TCP port), and max_wal_senders (replication connections). The pg_settings view is essential for administration—you can also check https://postgresqlco.nf/ to look up any parameter's context requirements. When automating configuration changes in scripts, always check pending_restart after making changes to avoid unexpected behavior. In containerized environments (Docker, Kubernetes), include restart logic in your deployment process or use configuration management tools that understand PostgreSQL's restart requirements.

Frequently asked questions

What does "Parameter requires restart" mean?
When PostgreSQL displays "Parameter requires restart," it means you attempted to change a configuration setting that requires a full server restart to take effect. PostgreSQL has different parameter contexts: postmaster parameters require a restart, SIGHUP parameters only need a reload, and user/session parameters can be changed immediately. Postmaster parameters typically control core server resources like memory allocation, connection limits, and protocol settings that cannot be modified while the server is running.
How do I fix "Parameter requires restart"?
PostgreSQL parameters with "postmaster" context cannot be changed without restarting the server. Learn how to identify restart-required parameters, apply changes correctly, and verify pending restarts.
What causes "Parameter requires restart"?
Attempting to change postmaster-context parameters without restarting the server Using ALTER SYSTEM or postgresql.conf to modify server resource parameters that require restart Confusing reload (which only applies SIGHUP parameters) with restart (needed for postmaster parameters)
Is the "Parameter requires restart" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading