Improve messages.

plugins/connection/docker.py

@@ -266,7 +266,9 @@ class Connection(ConnectionBase):
                     if not isinstance(val, str):
                         raise AnsibleConnectionFailure(
                             f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
-                            f"wrapped in quotes to avoid them being interpreted. {what}: {val!r}"
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
                         )
                 local_cmd += [
                     b"-e",

plugins/connection/docker_api.py

@@ -282,7 +282,9 @@ class Connection(ConnectionBase):
                     if not isinstance(val, str):
                         raise AnsibleConnectionFailure(
                             f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
-                            f"wrapped in quotes to avoid them being interpreted. {what}: {val!r}"
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
                         )
                 data["Env"].append(f"{k}={v}")
 

plugins/module_utils/_module_container/base.py

@@ -659,7 +659,9 @@ def _preprocess_env(
             if not isinstance(value, str):
                 module.fail_json(
                     msg="Non-string value found for env option. Ambiguous env options must be "
-                    f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
             final_env[name] = to_text(value, errors="surrogate_or_strict")
     formatted_env = []
@@ -947,7 +949,8 @@ def _preprocess_log(
                 value = to_text(v, errors="surrogate_or_strict")
                 module.warn(
                     f"Non-string value found for log_options option '{k}'. The value is automatically converted to {value!r}. "
-                    "If this is not correct, or you want to avoid such warnings, please quote the value."
+                    "If this is not correct, or you want to avoid such warnings, please quote the value,"
+                    " or explicitly convert the values to strings when templating them."
                 )
                 v = value
             options[k] = v

plugins/modules/docker_compose_v2_exec.py

@@ -214,7 +214,9 @@ class ExecManager(BaseComposeManager):
                 if not isinstance(value, str):
                     self.fail(
                         "Non-string value found for env option. Ambiguous env options must be "
-                        f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                        "wrapped in quotes to avoid them being interpreted when directly specified "
+                        "in YAML, or explicitly converted to strings when the option is templated. "
+                        f"Key: {name}"
                     )
 
     def get_exec_cmd(self, dry_run: bool) -> list[str]:

plugins/modules/docker_compose_v2_run.py

@@ -300,7 +300,9 @@ class ExecManager(BaseComposeManager):
                 if not isinstance(value, str):
                     self.fail(
                         "Non-string value found for env option. Ambiguous env options must be "
-                        f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                        "wrapped in quotes to avoid them being interpreted when directly specified "
+                        "in YAML, or explicitly converted to strings when the option is templated. "
+                        f"Key: {name}"
                     )
 
     def get_run_cmd(self, dry_run: bool) -> list[str]:

plugins/modules/docker_container_exec.py

@@ -228,7 +228,9 @@ def main() -> None:
             if not isinstance(value, str):
                 client.module.fail_json(
                     msg="Non-string value found for env option. Ambiguous env options must be "
-                    f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
 
     if command is not None:

plugins/modules/docker_swarm_service.py

@@ -914,8 +914,10 @@ def get_docker_environment(
         for name, value in env.items():
             if not isinstance(value, str):
                 raise ValueError(
-                    "Non-string value found for env option. "
+                    "Non-string value found for env option. Ambiguous env options must be "
-                    f"Ambiguous env options must be wrapped in quotes to avoid YAML parsing. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
             env_dict[name] = str(value)
     elif env is not None and isinstance(env, list):

tests/integration/targets/docker_container/tasks/tests/options.yml

@@ -3077,10 +3077,14 @@
     that:
       - log_options_1 is changed
       - log_options_2 is not changed
-      - "'Non-string value found for log_options option \\'max-file\\'. The value is automatically converted to \\'5\\'. If this is not correct, or you want to
+      - message in (log_options_2.warnings | default([]))
-  avoid such warnings, please quote the value.' in (log_options_2.warnings | default([]))"
       - log_options_3 is not changed
       - log_options_4 is changed
+  vars:
+    message: >-
+      Non-string value found for log_options option 'max-file'. The value is automatically converted to '5'.
+      If this is not correct, or you want to avoid such warnings, please quote the value,
+      or explicitly convert the values to strings when templating them.
 
 ####################################################################
 ## mac_address #####################################################