From 20c200b4a3920c2d2156481106b9c410638f7873 Mon Sep 17 00:00:00 2001
From: Nic <qianyong@api7.ai>
Date: Thu, 30 Apr 2026 17:34:04 +0800
Subject: [PATCH 1/2] fix: downgrade decrypt failure log from warn to info

During upgrades, when new fields are added to encrypt_fields, existing
plaintext data in etcd will fail to decrypt. This is a normal and expected
scenario, but the warn-level log generates noise that may alarm users.

Downgrade the log level from warn to info for decrypt operations and add
a hint message suggesting users re-save the configuration via Admin API
to encrypt the plaintext values.
---
 apisix/plugin.lua | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/apisix/plugin.lua b/apisix/plugin.lua
index 73d4df77fdbb..bd4f3beaffb3 100644
--- a/apisix/plugin.lua
+++ b/apisix/plugin.lua
@@ -993,7 +993,12 @@ end
 --   - Arbitrary depth dotted paths (e.g., "a.b.c.d")
 --   - Array traversal at intermediate nodes (iterate each element)
 --   - Leaf type dispatch: string, array of strings, map of strings
+local decrypt_hint = ". This is expected after upgrading if the field was recently "
+    .. "added to encrypt_fields; re-save the configuration via the Admin API to resolve."
+
 local function process_encrypt_field(conf, key_path, operation, plugin_name, op_name)
+    local log_func = op_name == "decrypt" and core.log.info or core.log.warn
+    local hint = op_name == "decrypt" and decrypt_hint or ""
     local dot_pos = core.string.find(key_path, ".")
 
     if not dot_pos then
@@ -1006,8 +1011,8 @@ local function process_encrypt_field(conf, key_path, operation, plugin_name, op_
         if type(val) == "string" then
             local result, err = operation(val, "data_encrypt")
             if not result then
-                core.log.warn("failed to ", op_name, " the conf of plugin [",
-                              plugin_name, "] key [", key_path, "], err: ", err)
+                log_func("failed to ", op_name, " the conf of plugin [",
+                         plugin_name, "] key [", key_path, "], err: ", err, hint)
             else
                 conf[key_path] = result
             end
@@ -1019,9 +1024,9 @@ local function process_encrypt_field(conf, key_path, operation, plugin_name, op_
                     if type(item) == "string" then
                         local result, err = operation(item, "data_encrypt")
                         if not result then
-                            core.log.warn("failed to ", op_name, " the conf of plugin [",
-                                          plugin_name, "] key [", key_path,
-                                          "] index [", i, "], err: ", err)
+                            log_func("failed to ", op_name, " the conf of plugin [",
+                                     plugin_name, "] key [", key_path,
+                                     "] index [", i, "], err: ", err, hint)
                         else
                             val[i] = result
                         end
@@ -1033,9 +1038,9 @@ local function process_encrypt_field(conf, key_path, operation, plugin_name, op_
                     if type(v) == "string" then
                         local result, err = operation(v, "data_encrypt")
                         if not result then
-                            core.log.warn("failed to ", op_name, " the conf of plugin [",
-                                          plugin_name, "] key [", key_path,
-                                          ".", k, "], err: ", err)
+                            log_func("failed to ", op_name, " the conf of plugin [",
+                                     plugin_name, "] key [", key_path,
+                                     ".", k, "], err: ", err, hint)
                         else
                             val[k] = result
                         end

From de7b7c8718200cfd013c1c9ca0c8a6c4f5cc076b Mon Sep 17 00:00:00 2001
From: Nic <qianyong@api7.ai>
Date: Thu, 30 Apr 2026 17:39:22 +0800
Subject: [PATCH 2/2] fix: soften decrypt hint wording to avoid misleading
 operators

Use 'This can happen' instead of 'This is expected' and add a note
about verifying the data_encryption keyring for genuine failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 apisix/plugin.lua | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/apisix/plugin.lua b/apisix/plugin.lua
index bd4f3beaffb3..b69ba33a8418 100644
--- a/apisix/plugin.lua
+++ b/apisix/plugin.lua
@@ -993,8 +993,9 @@ end
 --   - Arbitrary depth dotted paths (e.g., "a.b.c.d")
 --   - Array traversal at intermediate nodes (iterate each element)
 --   - Leaf type dispatch: string, array of strings, map of strings
-local decrypt_hint = ". This is expected after upgrading if the field was recently "
-    .. "added to encrypt_fields; re-save the configuration via the Admin API to resolve."
+local decrypt_hint = ". This can happen after upgrading if the field was recently "
+    .. "added to encrypt_fields; if the value was encrypted, verify the data_encryption "
+    .. "keyring. Re-save the configuration via the Admin API to resolve."
 
 local function process_encrypt_field(conf, key_path, operation, plugin_name, op_name)
     local log_func = op_name == "decrypt" and core.log.info or core.log.warn