From: Fujii Masao <fujii@postgresql.org>
Date: Thu, 20 Nov 2025 00:14:02 +0000 (+0900)
Subject: Add HINT listing valid encodings to encode() and decode() errors.
X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=99780da7209605bf9f226eac3eac30ab2bc9427c;p=postgresql.git

Add HINT listing valid encodings to encode() and decode() errors.

This commit updates encode() and decode() so that when an invalid encoding
is specified, their error message includes a HINT listing all valid encodings.
This helps users quickly see which encodings are supported without needing
to consult the documentation.

Author: Shinya Sugamoto <shinya34892@gmail.com>
Reviewed-by: Chao Li <lic@highgo.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Masahiko Sawada <sawada.mshk@gmail.com>
Reviewed-by: Peter Eisentraut <peter@eisentraut.org>
Reviewed-by: Nathan Bossart <nathandbossart@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/CAAe3y+99sfPv8UDF1VM-rC1i5HBdqxUh=2HrbJJFm2+i=1OwOw@mail.gmail.com
---

diff --git a/src/backend/utils/adt/encode.c b/src/backend/utils/adt/encode.c
index aabe9913eee..c813ee1258b 100644
--- a/src/backend/utils/adt/encode.c
+++ b/src/backend/utils/adt/encode.c
@@ -64,7 +64,9 @@ binary_encode(PG_FUNCTION_ARGS)
 	if (enc == NULL)
 		ereport(ERROR,
 				(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
-				 errmsg("unrecognized encoding: \"%s\"", namebuf)));
+				 errmsg("unrecognized encoding: \"%s\"", namebuf),
+				 errhint("Valid encodings are \"%s\", \"%s\", \"%s\", and \"%s\".",
+						 "base64", "base64url", "escape", "hex")));
 
 	dataptr = VARDATA_ANY(data);
 	datalen = VARSIZE_ANY_EXHDR(data);
@@ -112,7 +114,9 @@ binary_decode(PG_FUNCTION_ARGS)
 	if (enc == NULL)
 		ereport(ERROR,
 				(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
-				 errmsg("unrecognized encoding: \"%s\"", namebuf)));
+				 errmsg("unrecognized encoding: \"%s\"", namebuf),
+				 errhint("Valid encodings are \"%s\", \"%s\", \"%s\", and \"%s\".",
+						 "base64", "base64url", "escape", "hex")));
 
 	dataptr = VARDATA_ANY(data);
 	datalen = VARSIZE_ANY_EXHDR(data);
diff --git a/src/test/regress/expected/strings.out b/src/test/regress/expected/strings.out
index b9dc08d5f61..727304f60e7 100644
--- a/src/test/regress/expected/strings.out
+++ b/src/test/regress/expected/strings.out
@@ -2575,6 +2575,13 @@ SELECT decode(encode('\x1234567890abcdef00', 'escape'), 'escape');
  \x1234567890abcdef00
 (1 row)
 
+-- report an error with a hint listing valid encodings when an invalid encoding is specified
+SELECT encode('\x01'::bytea, 'invalid');  -- error
+ERROR:  unrecognized encoding: "invalid"
+HINT:  Valid encodings are "base64", "base64url", "escape", and "hex".
+SELECT decode('00', 'invalid');           -- error
+ERROR:  unrecognized encoding: "invalid"
+HINT:  Valid encodings are "base64", "base64url", "escape", and "hex".
 --
 -- base64url encoding/decoding
 --
diff --git a/src/test/regress/sql/strings.sql b/src/test/regress/sql/strings.sql
index a2a91523404..88aa4c2983b 100644
--- a/src/test/regress/sql/strings.sql
+++ b/src/test/regress/sql/strings.sql
@@ -815,6 +815,10 @@ SELECT decode(encode(('\x' || repeat('1234567890abcdef0001', 7))::bytea,
 SELECT encode('\x1234567890abcdef00', 'escape');
 SELECT decode(encode('\x1234567890abcdef00', 'escape'), 'escape');
 
+-- report an error with a hint listing valid encodings when an invalid encoding is specified
+SELECT encode('\x01'::bytea, 'invalid');  -- error
+SELECT decode('00', 'invalid');           -- error
+
 --
 -- base64url encoding/decoding
 --