From d4dd572047f0ff485eb6826bcd93e38451f1bc82 Mon Sep 17 00:00:00 2001
From: "stephenonyango65@gmail.com" <steveotieno5640@gmail.com>
Date: Tue, 17 Feb 2026 11:49:34 +0300
Subject: [PATCH 1/4] FuncParamType should use ValueError message in
 self.fail()

When FuncParamType.convert() caught a ValueError, it discarded the
exception message and only passed the input value to self.fail(). This
meant users lost context about why the conversion failed.

This fix captures and uses the ValueError message, providing better error
feedback to users. Falls back to the input value only if the message is
empty (backward compatibility).

Includes regression test ensuring the message is surfaced in the
BadParameter exception.
---
 src/click/types.py  | 15 +++++++++------
 tests/test_types.py | 12 ++++++++++++
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/src/click/types.py b/src/click/types.py
index e71c1c21e4..5177cdb022 100644
--- a/src/click/types.py
+++ b/src/click/types.py
@@ -183,13 +183,16 @@ def convert(
     ) -> t.Any:
         try:
             return self.func(value)
-        except ValueError:
-            try:
-                value = str(value)
-            except UnicodeError:
-                value = value.decode("utf-8", "replace")
+        except ValueError as exc:
+            message = str(exc)
+
+            if not message:
+                try:
+                    message = str(value)
+                except UnicodeError:
+                    message = value.decode("utf-8", "replace")
 
-            self.fail(value, param, ctx)
+            self.fail(message, param, ctx)
 
 
 class UnprocessedParamType(ParamType):
diff --git a/tests/test_types.py b/tests/test_types.py
index 75434f1042..2e1f902879 100644
--- a/tests/test_types.py
+++ b/tests/test_types.py
@@ -51,6 +51,18 @@ def test_range_fail(type, value, expect):
     assert expect in exc_info.value.message
 
 
+def test_func_param_type_uses_value_error_message():
+    def parse(value):
+        raise ValueError(f"bad value: {value}")
+
+    func_type = click.types.FuncParamType(parse)
+
+    with pytest.raises(click.BadParameter) as exc_info:
+        func_type.convert("nope", None, None)
+
+    assert "bad value: nope" in exc_info.value.message
+
+
 def test_float_range_no_clamp_open():
     with pytest.raises(TypeError):
         click.FloatRange(0, 1, max_open=True, clamp=True)

From b92317719c61a6fa023b857f97084986b7e672e1 Mon Sep 17 00:00:00 2001
From: Andreas Backx <andreas@backx.org>
Date: Thu, 30 Apr 2026 01:32:56 +0100
Subject: [PATCH 2/4] Add CHANGES entry.

---
 CHANGES.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGES.rst b/CHANGES.rst
index 774d596749..cb847dde8e 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -4,6 +4,8 @@ Unreleased
 
 -   Fix handling of ``flag_value`` when ``is_flag=False`` to allow such options to be
     used without an explicit value. :issue:`3084`
+-   Use :class:`ValueError` message when conversion in :class:`FuncParamType` would
+    fail. :issue:`3105` :pr:`3211`
 
 Version 8.3.1
 --------------

From 22aeb7bcd7c2a20c1a7acfcf4c63fb59bdb99de1 Mon Sep 17 00:00:00 2001
From: Andreas Backx <andreas@backx.org>
Date: Thu, 30 Apr 2026 01:36:40 +0100
Subject: [PATCH 3/4] Move change entry to new 8.3.4.

---
 CHANGES.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 867dd208e8..e143a5f686 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,5 +1,13 @@
 .. currentmodule:: click
 
+Version 8.3.4
+-------------
+
+Unreleased
+
+-   Use :class:`ValueError` message when conversion in :class:`FuncParamType` would
+    fail. :issue:`3105` :pr:`3211`
+
 Version 8.3.3
 -------------
 
@@ -58,8 +66,6 @@ Released 2026-04-02
     with a dedicated CI job. :pr:`3139`
 -   Fix callable ``flag_value`` being instantiated when used as a default via
     ``default=True``. :issue:`3121` :pr:`3201` :pr:`3213` :pr:`3225`
--   Use :class:`ValueError` message when conversion in :class:`FuncParamType` would
-    fail. :issue:`3105` :pr:`3211`
 
 Version 8.3.1
 -------------

From f27d80b067c1a6ad22a0c8422e56fad21162c9b5 Mon Sep 17 00:00:00 2001
From: Andreas Backx <AndreasBackx@users.noreply.github.com>
Date: Thu, 30 Apr 2026 22:56:55 +0100
Subject: [PATCH 4/4] Remove empty line before version header

---
 CHANGES.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 0ef2026b97..21bf29323d 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,6 +1,5 @@
 .. currentmodule:: click
 
-
 Version 8.4.0
 -------------