Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PostgreSQL says postgresql.conf has errors and a setting does not apply

Errorpostgresql.conf contains errors

Short answer

PostgreSQL logs invalid settings and ignores them on reload, so a change can silently not apply. Query the pg_file_settings view: its error column and applied flag point at the exact file and line. Usual causes are an unquoted value, an include file that is missing, or a setting that needs a restart.

  • Applies to PostgreSQL 17, PostgreSQL 18
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the running server which lines it rejected. Rows with an error value, or applied = f, are the ones to fix. If the server will not start, read the server log instead.

    SELECT sourcefile, sourceline, name, setting, applied, error
    FROM pg_file_settings
    WHERE error IS NOT NULL OR NOT applied;
  2. 2Match what you see, then jump to its fix

    1. 1error column names the parameter on that lineA value is not quoted, or a unit is written wronglyFix
    2. 2pg_file_settings shows nothing from the included file, or the log names the includeAn include line points at a file that does not existFix
    3. 3a row shows applied = f but no error, and the value in SHOW is the old oneThe setting needs a restart, or another file overrides itFix

What does the error look like?

  • postgresql.conf contains errors
  • a changed setting does not take effect after pg_reload_conf()

Cause 1 of 3

A value is not quoted, or a unit is written wrongly

1Check

Values that are not simple identifiers or numbers need single quotes. A value with units, such as 30min, has to be written as a quoted string for the unit to work. Do not use thousands separators.

SELECT sourcefile, sourceline, name, setting, error FROM pg_file_settings WHERE error IS NOT NULL;

2Fix

Quote text values with single quotes (double a single quote inside), and write numbers plainly.

search_path = '"$user", public'
shared_buffers = 128MB
log_destination = 'stderr'

3Verify

Reload and confirm no row shows an error.

SELECT pg_reload_conf();
SELECT count(*) FROM pg_file_settings WHERE error IS NOT NULL;

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

An include line points at a file that does not exist

1Check

include 'file' treats a missing or unreadable file as a problem; include_if_exists logs a message and carries on. A relative name is resolved from the directory of the file that contains the line.

grep -n -E "^\s*include" /etc/postgresql/17/main/postgresql.conf

2Fix

Correct the path, create the file, or switch to include_if_exists if the file is optional.

include_if_exists 'local_overrides.conf'
include_dir 'conf.d'

3Verify

Reload, then check that the settings from the included files show applied = t.

SELECT sourcefile, name, applied FROM pg_file_settings WHERE sourcefile LIKE '%conf.d%';

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

The setting needs a restart, or another file overrides it

1Check

Some parameters only change at server start; a reload ignores them. Also only the last entry for a parameter counts, and postgresql.auto.conf, written by ALTER SYSTEM, overrides postgresql.conf.

SELECT name, setting, sourcefile, sourceline, applied
FROM pg_file_settings WHERE name = 'shared_buffers';

2Fix

Restart the server for restart-only settings. If postgresql.auto.conf holds an override, remove it with ALTER SYSTEM, or set the value again through ALTER SYSTEM.

ALTER SYSTEM SET shared_buffers = '256MB';
-- then restart the service, e.g. sudo systemctl restart postgresql

3Verify

SHOW returns the value from postgresql.conf.

SHOW shared_buffers;

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Check pg_file_settings after every edit and before restarting a production server.
  • Keep local changes in an include_dir folder, with numbered file names to set the order.
  • Avoid editing postgresql.auto.conf by hand while the server is running.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.