From 7d2aa2a4c6483e237bf22106ab00ab2e9f19beba Mon Sep 17 00:00:00 2001
From: Ariel Otilibili <30573755+ariel-anieli@users.noreply.github.com>
Date: Sat, 21 Mar 2026 02:07:35 +0100
Subject: [PATCH] find: add locale encoding in err msg when none is given
 (#86641)

When the search fails, as expected, the following error is printed out:

    [...] Failed to read the file FILENAME due to an encoding error. current encoding: None (default determined by the Python built-in function "open")

Add locale encoding in error messages when none is given.

As well, this case is hit for decoding exceptions, not encoding ones.

Change the error message.

Add the corresponding tests, update documentation.

Link: https://docs.python.org/3/library/locale.html#locale.getpreferredencoding
Co-authored-by: Matt Clay <matt@mystile.com>
Signed-off-by: Ariel Otilibili <a.otilibili@instadeep.com>
---
 changelogs/fragments/find-default-encoding.yml |  3 +++
 lib/ansible/modules/find.py                    | 11 +++++++++--
 test/integration/targets/find/tasks/main.yml   | 18 +++++++++++++++++-
 3 files changed, 29 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/fragments/find-default-encoding.yml

diff --git a/changelogs/fragments/find-default-encoding.yml b/changelogs/fragments/find-default-encoding.yml
new file mode 100644
index 00000000000..7a0d67002a7
--- /dev/null
+++ b/changelogs/fragments/find-default-encoding.yml
@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - find - add locale encoding in err msg when none is given
diff --git a/lib/ansible/modules/find.py b/lib/ansible/modules/find.py
index b6fe0deaa4a..8e40298fdab 100644
--- a/lib/ansible/modules/find.py
+++ b/lib/ansible/modules/find.py
@@ -152,6 +152,7 @@ options:
     encoding:
         description:
             - When doing a O(contains) search, determine the encoding of the files to be searched.
+            - When no value is provided, the Python default encoding is used.
         type: str
         version_added: "2.17"
     limit:
@@ -283,6 +284,7 @@ skipped_paths:
 import errno
 import fnmatch
 import grp
+import locale
 import os
 import pwd
 import re
@@ -388,8 +390,13 @@ def contentfilter(fsname, pattern, encoding, read_whole_file=False):
         raise e
     except UnicodeDecodeError as e:
         if encoding is None:
-            encoding = 'None (default determined by the Python built-in function "open")'
-        msg = f'Failed to read the file {fsname} due to an encoding error. current encoding: {encoding}'
+            # Get the default encoding for the current locale
+            # This is the same encoding that the open() function uses by default
+            # when no encoding is specified. This value is platform dependent.
+            #
+            # https://docs.python.org/3/library/functions.html#open
+            encoding = f"{locale.getpreferredencoding(False).lower()} (Python default)"
+        msg = f'Failed to decode the file {fsname!r} with encoding: {encoding}'
         raise Exception(msg) from e
     except Exception:
         pass
diff --git a/test/integration/targets/find/tasks/main.yml b/test/integration/targets/find/tasks/main.yml
index a2edc1123f1..440763c3aa1 100644
--- a/test/integration/targets/find/tasks/main.yml
+++ b/test/integration/targets/find/tasks/main.yml
@@ -211,7 +211,23 @@
           - fail_to_read_wrong_encoding_file.msg == 'Not all paths examined, check warnings for details'
           - >-
               fail_to_read_wrong_encoding_file.skipped_paths[remote_tmp_dir_test] ==
-              ("Failed to read the file %s/hello_world.gbk due to an encoding error. current encoding: utf-8" % (remote_tmp_dir_test))
+              ("Failed to decode the file '%s/hello_world.gbk' with encoding: utf-8" % (remote_tmp_dir_test))
+
+- name: read a gbk file with no encoding specified (uses locale default)
+  find:
+    paths: "{{ remote_tmp_dir_test }}"
+    patterns: "*.gbk"
+    contains: "你好世界"
+  register: fail_to_read_default_encoding
+
+- name: Verify error message shows locale encoding name
+  vars:
+    error_pattern: 'Failed to decode the file .+ with encoding: .+ \(Python default\)'
+  assert:
+    that:
+      - fail_to_read_default_encoding.msg == 'Not all paths examined, check warnings for details'
+      - fail_to_read_default_encoding.skipped_paths[remote_tmp_dir_test] is search("^" + error_pattern + "$")
+      - fail_to_read_default_encoding.warnings | select('search', error_pattern) | list | length >= 1
 
 - name: read a gbk file by gbk
   find: