[PATCH] Add hint to wal_level errors for replication slots and pg_log_standby_snapshot

Started by Joao Rito4 days ago4 messageshackers
Jump to latest
#1Joao Rito
joaovictor.rito@gmail.com

Two errors tell the user that wal_level must be at least "replica" but
give no hint on how to fix it. The similar errors for existing slots in
RestoreSlotFromDisk() already say:

Change "wal_level" to be "replica" or higher.

Add that hint to the error in CheckSlotRequirements() and to the one in
pg_log_standby_snapshot(). Since wal_level can only be changed at server
start, also tell the user to restart, using the wording of a hint in
xlogrecovery.c:

Restart the server after making the necessary configuration changes.

"replica" is enough for every caller of CheckSlotRequirements(),
including REPACK, which has its own check in
check_concurrent_repack_requirements() that also asks for "replica" or
higher.
---
Hi,

I may have missed something, so please correct me where I am wrong.

When wal_level is "minimal", two errors say that wal_level must be at least "replica", but give no hint on what to do:

ERROR: replication slots can only be used if "wal_level" >= "replica"
ERROR: pg_log_standby_snapshot() can only be used if "wal_level" >= "replica"

The errors for existing slots in RestoreSlotFromDisk() already have this hint:

HINT: Change "wal_level" to be "replica" or higher.

The attached patch adds that hint to the error in CheckSlotRequirements() and to the one in pg_log_standby_snapshot(). Because wal_level changes only at server start, I also added the sentence from a hint in xlogrecovery.c: "Restart the server after making the necessary configuration changes." The msgid of both errmsg lines does not change.

I looked at REPACK, which also reaches CheckSlotRequirements(). check_concurrent_repack_requirements() already requires "replica" or higher, so the hint is correct there too.

I tested on current master with --enable-cassert and --enable-tap-tests. With wal_level=minimal, both errors show the hint after the patch and not before. "make check" passed (243 tests), "make check" in src/test/recovery passed (695 tests), and pgindent shows no diff on the 2 files.

What I did not test: builds with --enable-nls and translations, meson, other platforms, an actual REPACK run, and the injection-point recovery tests that were skipped. I did not add a regression test, because I found no existing test that checks these messages, and a new TAP test seemed too heavy for this change.

Does this direction make sense? If the hint is redundant, or the wording should change, I am happy to adjust or drop the patch.

Thank you for your time.

src/backend/access/transam/xlogfuncs.c | 3 ++-
src/backend/replication/slot.c | 3 ++-
2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/backend/access/transam/xlogfuncs.c b/src/backend/access/transam/xlogfuncs.c
index 1f52bf7..4ec42c4 100644
--- a/src/backend/access/transam/xlogfuncs.c
+++ b/src/backend/access/transam/xlogfuncs.c
@@ -243,7 +243,8 @@ pg_log_standby_snapshot(PG_FUNCTION_ARGS)
 	if (!XLogStandbyInfoActive())
 		ereport(ERROR,
 				(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
-				 errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\"")));
+				 errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\""),
+				 errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));

recptr = LogStandbySnapshot();

diff --git a/src/backend/replication/slot.c b/src/backend/replication/slot.c
index a311aee..64f4578 100644
--- a/src/backend/replication/slot.c
+++ b/src/backend/replication/slot.c
@@ -1690,7 +1690,8 @@ CheckSlotRequirements(bool repack)
 	if (wal_level < WAL_LEVEL_REPLICA)
 		ereport(ERROR,
 				(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
-				 errmsg("replication slots can only be used if \"wal_level\" >= \"replica\"")));
+				 errmsg("replication slots can only be used if \"wal_level\" >= \"replica\""),
+				 errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));
 }

/*
--
2.39.5

#2Chao Li
li.evan.chao@gmail.com
In reply to: Joao Rito (#1)
Re: [PATCH] Add hint to wal_level errors for replication slots and pg_log_standby_snapshot

On Nov 19, 2026, at 07:46, Joao Rito <joaovictor.rito@gmail.com> wrote:

Two errors tell the user that wal_level must be at least "replica" but
give no hint on how to fix it. The similar errors for existing slots in
RestoreSlotFromDisk() already say:

Change "wal_level" to be "replica" or higher.

Add that hint to the error in CheckSlotRequirements() and to the one in
pg_log_standby_snapshot(). Since wal_level can only be changed at server
start, also tell the user to restart, using the wording of a hint in
xlogrecovery.c:

Restart the server after making the necessary configuration changes.

"replica" is enough for every caller of CheckSlotRequirements(),
including REPACK, which has its own check in
check_concurrent_repack_requirements() that also asks for "replica" or
higher.
---
Hi,

I may have missed something, so please correct me where I am wrong.

When wal_level is "minimal", two errors say that wal_level must be at least "replica", but give no hint on what to do:

ERROR: replication slots can only be used if "wal_level" >= "replica"
ERROR: pg_log_standby_snapshot() can only be used if "wal_level" >= "replica"

The errors for existing slots in RestoreSlotFromDisk() already have this hint:

HINT: Change "wal_level" to be "replica" or higher.

The attached patch adds that hint to the error in CheckSlotRequirements() and to the one in pg_log_standby_snapshot(). Because wal_level changes only at server start, I also added the sentence from a hint in xlogrecovery.c: "Restart the server after making the necessary configuration changes." The msgid of both errmsg lines does not change.

I looked at REPACK, which also reaches CheckSlotRequirements(). check_concurrent_repack_requirements() already requires "replica" or higher, so the hint is correct there too.

I tested on current master with --enable-cassert and --enable-tap-tests. With wal_level=minimal, both errors show the hint after the patch and not before. "make check" passed (243 tests), "make check" in src/test/recovery passed (695 tests), and pgindent shows no diff on the 2 files.

What I did not test: builds with --enable-nls and translations, meson, other platforms, an actual REPACK run, and the injection-point recovery tests that were skipped. I did not add a regression test, because I found no existing test that checks these messages, and a new TAP test seemed too heavy for this change.

Does this direction make sense? If the hint is redundant, or the wording should change, I am happy to adjust or drop the patch.

Thank you for your time.

src/backend/access/transam/xlogfuncs.c | 3 ++-
src/backend/replication/slot.c | 3 ++-
2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/backend/access/transam/xlogfuncs.c b/src/backend/access/transam/xlogfuncs.c
index 1f52bf7..4ec42c4 100644
--- a/src/backend/access/transam/xlogfuncs.c
+++ b/src/backend/access/transam/xlogfuncs.c
@@ -243,7 +243,8 @@ pg_log_standby_snapshot(PG_FUNCTION_ARGS)
if (!XLogStandbyInfoActive())
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\"")));
+ errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\""),
+ errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));

recptr = LogStandbySnapshot();

diff --git a/src/backend/replication/slot.c b/src/backend/replication/slot.c
index a311aee..64f4578 100644
--- a/src/backend/replication/slot.c
+++ b/src/backend/replication/slot.c
@@ -1690,7 +1690,8 @@ CheckSlotRequirements(bool repack)
if (wal_level < WAL_LEVEL_REPLICA)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("replication slots can only be used if \"wal_level\" >= \"replica\"")));
+ errmsg("replication slots can only be used if \"wal_level\" >= \"replica\""),
+ errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));
}

/*
--
2.39.5

I’m not against adding the hint message. I think the hint message can be shorter, and there should be two white spaces between sentences. So, how about:
```
errhint("Set \"wal_level\" to \"replica\" or higher and restart the server.")
```

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

#3Zhijie Hou
houzhijie22@gmail.com
In reply to: Chao Li (#2)
Re: [PATCH] Add hint to wal_level errors for replication slots and pg_log_standby_snapshot

Hi,

On Thu, Nov19, 2026 at 09:05 AM Chao Li wrote:

On Nov 19, 2026, at 07:46, Joao Rito <joaovictor.rito@gmail.com> wrote:

Two errors tell the user that wal_level must be at least "replica"
but give no hint on how to fix it. The similar errors for existing
slots in RestoreSlotFromDisk() already say:

Change "wal_level" to be "replica" or higher.

Add that hint to the error in CheckSlotRequirements() and to the one
in pg_log_standby_snapshot(). Since wal_level can only be changed at
server start, also tell the user to restart, using the wording of a
hint in xlogrecovery.c:

Restart the server after making the necessary configuration changes.

"replica" is enough for every caller of CheckSlotRequirements(),
including REPACK, which has its own check in
check_concurrent_repack_requirements() that also asks for "replica"
or higher.
---

src/backend/access/transam/xlogfuncs.c | 3 ++-
src/backend/replication/slot.c | 3 ++-
2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/backend/access/transam/xlogfuncs.c b/src/backend/access/transam/xlogfuncs.c
index 1f52bf7..4ec42c4 100644
--- a/src/backend/access/transam/xlogfuncs.c
+++ b/src/backend/access/transam/xlogfuncs.c
@@ -243,7 +243,8 @@ pg_log_standby_snapshot(PG_FUNCTION_ARGS)
if (!XLogStandbyInfoActive())
ereport(ERROR, (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\"")));
+ errmsg("pg_log_standby_snapshot() can only be used if \"wal_level\" >= \"replica\""),
+ errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));

recptr = LogStandbySnapshot();

diff --git a/src/backend/replication/slot.c b/src/backend/replication/slot.c
index a311aee..64f4578 100644
--- a/src/backend/replication/slot.c
+++ b/src/backend/replication/slot.c
@@ -1690,7 +1690,8 @@ CheckSlotRequirements(bool repack)
if (wal_level < WAL_LEVEL_REPLICA)
ereport(ERROR, (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("replication slots can only be used if \"wal_level\" >= \"replica\"")));
+ errmsg("replication slots can only be used if \"wal_level\" >= \"replica\""),
+ errhint("Change \"wal_level\" to be \"replica\" or higher. Restart the server after making the necessary configuration changes.")));
}

I’m not against adding the hint message. I think the hint message can
be shorter, and there should be two white spaces between sentences.
So, how about: ``` errhint("Set \"wal_level\" to \"replica\" or higher
and restart the server.") ```

I don't think these two errors need an additional hint, as the primary
error messages here already explicitly state the required setting and
value ("... can only be used if \"wal_level\" >= \"replica\"").
Repeating that in errhint() would be redundant.

--
Best Regards,
Zhijie Hou

#4Joao Rito
joaovictor.rito@gmail.com
In reply to: Joao Rito (#1)
Re: [PATCH] Add hint to wal_level errors for replication slots and pg_log_standby_snapshot

Hi Chao, Zhijie,

Thank you both for the feedback.

Zhijie, that is a fair point. The primary messages already state the required setting and value, so the hint repeats it. Chao, thank you for the shorter wording and the note about two spaces between sentences.

Unless someone thinks the hint is useful, I will drop this patch. If somebody prefers to keep it, I will send a new version with Chao's wording:

errhint("Set \"wal_level\" to \"replica\" or higher and restart the server.")

Thanks again,
Joao Rito