From 2f48a56482d8bd0d205c3ae9c1945250c2b0dd4e Mon Sep 17 00:00:00 2001
From: Aarni Koskela <akx@iki.fi>
Date: Thu, 9 Jul 2026 10:20:58 +0300
Subject: [PATCH 1/5] Add PIL._imaging.NotSupportedError

---
 src/_imaging.c           | 31 +++++++++++++++++++++++++++++++
 src/libImaging/Imaging.h |  4 ++++
 2 files changed, 35 insertions(+)

diff --git a/src/_imaging.c b/src/_imaging.c
index 897e718e30a..fd18e7317fb 100644
--- a/src/_imaging.c
+++ b/src/_imaging.c
@@ -382,6 +382,19 @@ ImagingError_ModeError(void) {
     return NULL;
 }
 
+// Derives from both NotImplementedError and ValueError
+// (as the functions above raise ValueErrors).
+static PyObject *ImagingNotSupportedError = NULL;
+
+void *
+ImagingError_NotSupportedError(const char *message) {
+    PyErr_SetString(
+        ImagingNotSupportedError ? ImagingNotSupportedError : PyExc_NotImplementedError,
+        (message) ? (char *)message : "operation not supported"
+    );
+    return NULL;
+}
+
 void *
 ImagingError_ValueError(const char *message) {
     PyErr_SetString(
@@ -4326,6 +4339,24 @@ setup_module(PyObject *m) {
         return -1;
     }
 
+    if (ImagingNotSupportedError == NULL) {
+        // NotSupportedError derives from both NotImplementedError and ValueError,
+        // for compatibility with `except ValueError`.
+        PyObject *bases = PyTuple_Pack(2, PyExc_NotImplementedError, PyExc_ValueError);
+        if (bases == NULL) {
+            return -1;
+        }
+        ImagingNotSupportedError =
+            PyErr_NewException("PIL._imaging.NotSupportedError", bases, NULL);
+        Py_DECREF(bases);
+        if (ImagingNotSupportedError == NULL) {
+            return -1;
+        }
+    }
+    if (PyModule_AddObjectRef(m, "NotSupportedError", ImagingNotSupportedError) < 0) {
+        return -1;
+    }
+
 #ifdef HAVE_LIBJPEG
     {
         extern const char *ImagingJpegVersion(void);
diff --git a/src/libImaging/Imaging.h b/src/libImaging/Imaging.h
index 472bda5d0fd..00c148f5d60 100644
--- a/src/libImaging/Imaging.h
+++ b/src/libImaging/Imaging.h
@@ -273,6 +273,10 @@ extern void *
 ImagingError_Mismatch(void); /* maps to ValueError by default */
 extern void *
 ImagingError_ValueError(const char *message);
+extern void *
+ImagingError_NotSupportedError(
+    const char *message
+); /* derives from NotImplementedError and ValueError */
 
 /* Transform callbacks */
 /* ------------------- */

From 35c042699b6794ce42fa2235dd73d94f8dc7e50f Mon Sep 17 00:00:00 2001
From: Aarni Koskela <akx@iki.fi>
Date: Thu, 9 Jul 2026 11:10:07 +0300
Subject: [PATCH 2/5] Fix unused-variable nit

---
 src/_imaging.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/_imaging.c b/src/_imaging.c
index fd18e7317fb..c03f43e0ac7 100644
--- a/src/_imaging.c
+++ b/src/_imaging.c
@@ -328,7 +328,6 @@ _new_arrow(PyObject *self, PyObject *args) {
     ModeID mode_id;
     int xsize, ysize;
     PyObject *schema_capsule, *array_capsule;
-    PyObject *ret;
 
     if (!PyArg_ParseTuple(
             args, "s(ii)OO", &mode, &xsize, &ysize, &schema_capsule, &array_capsule

From 946d6ae006c2ef7c7afb64551200f9e11a71dca4 Mon Sep 17 00:00:00 2001
From: Aarni Koskela <akx@iki.fi>
Date: Thu, 9 Jul 2026 10:23:11 +0300
Subject: [PATCH 3/5] Allow custom error message for ImagingError_ModeError and
 ImagingError_Mismatch

---
 src/_imaging.c                  | 12 ++++++++----
 src/libImaging/AlphaComposite.c |  4 ++--
 src/libImaging/Bands.c          | 14 +++++++-------
 src/libImaging/Blend.c          |  4 ++--
 src/libImaging/BoxBlur.c        |  6 +++---
 src/libImaging/Chops.c          |  4 ++--
 src/libImaging/ColorLUT.c       |  4 ++--
 src/libImaging/Convert.c        |  8 ++++----
 src/libImaging/Crop.c           |  2 +-
 src/libImaging/Dib.c            |  2 +-
 src/libImaging/Fill.c           |  4 ++--
 src/libImaging/Filter.c         |  2 +-
 src/libImaging/Geometry.c       | 34 ++++++++++++++++-----------------
 src/libImaging/GetBBox.c        |  6 +++---
 src/libImaging/Histo.c          |  6 +++---
 src/libImaging/Imaging.h        |  4 ++--
 src/libImaging/Matrix.c         |  4 ++--
 src/libImaging/ModeFilter.c     |  2 +-
 src/libImaging/Negative.c       |  2 +-
 src/libImaging/Offset.c         |  2 +-
 src/libImaging/Palette.c        |  2 +-
 src/libImaging/Paste.c          | 10 +++++-----
 src/libImaging/Point.c          |  4 ++--
 src/libImaging/Quant.c          |  6 +++---
 src/libImaging/RankFilter.c     |  4 ++--
 src/libImaging/Reduce.c         |  4 ++--
 src/libImaging/Resample.c       |  6 +++---
 src/libImaging/Storage.c        |  2 +-
 28 files changed, 84 insertions(+), 80 deletions(-)

diff --git a/src/_imaging.c b/src/_imaging.c
index c03f43e0ac7..95176300049 100644
--- a/src/_imaging.c
+++ b/src/_imaging.c
@@ -370,14 +370,18 @@ ImagingError_MemoryError(void) {
 }
 
 void *
-ImagingError_Mismatch(void) {
-    PyErr_SetString(PyExc_ValueError, "images do not match");
+ImagingError_Mismatch(const char *message) {
+    PyErr_SetString(
+        PyExc_ValueError, (message) ? (char *)message : "images do not match"
+    );
     return NULL;
 }
 
 void *
-ImagingError_ModeError(void) {
-    PyErr_SetString(PyExc_ValueError, "image has wrong mode");
+ImagingError_ModeError(const char *message) {
+    PyErr_SetString(
+        PyExc_ValueError, (message) ? (char *)message : "image has wrong mode"
+    );
     return NULL;
 }
 
diff --git a/src/libImaging/AlphaComposite.c b/src/libImaging/AlphaComposite.c
index d1a1e7ad34a..0718e2ab1d7 100644
--- a/src/libImaging/AlphaComposite.c
+++ b/src/libImaging/AlphaComposite.c
@@ -26,12 +26,12 @@ ImagingAlphaComposite(Imaging imDst, Imaging imSrc) {
     /* Check arguments */
     if (!imDst || !imSrc ||
         (imDst->mode != IMAGING_MODE_RGBA && imDst->mode != IMAGING_MODE_LA)) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     if (imDst->mode != imSrc->mode || imDst->xsize != imSrc->xsize ||
         imDst->ysize != imSrc->ysize) {
-        return ImagingError_Mismatch();
+        return ImagingError_Mismatch(NULL);
     }
 
     imOut = ImagingNewDirty(imDst->mode, imDst->xsize, imDst->ysize);
diff --git a/src/libImaging/Bands.c b/src/libImaging/Bands.c
index d1fa16addff..53e15771bfb 100644
--- a/src/libImaging/Bands.c
+++ b/src/libImaging/Bands.c
@@ -24,7 +24,7 @@ ImagingGetBand(Imaging imIn, int band) {
 
     /* Check arguments */
     if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (band < 0 || band >= imIn->bands) {
@@ -74,7 +74,7 @@ ImagingSplit(Imaging imIn, Imaging bands[4]) {
 
     /* Check arguments */
     if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        (void)ImagingError_ModeError();
+        (void)ImagingError_ModeError(NULL);
         return 0;
     }
 
@@ -179,7 +179,7 @@ ImagingPutBand(Imaging imOut, Imaging imIn, int band) {
 
     /* Check arguments */
     if (!imIn || imIn->bands != 1 || !imOut) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (band < 0 || band >= imOut->bands) {
@@ -188,7 +188,7 @@ ImagingPutBand(Imaging imOut, Imaging imIn, int band) {
 
     if (imIn->type != imOut->type || imIn->xsize != imOut->xsize ||
         imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     /* Shortcuts */
@@ -225,7 +225,7 @@ ImagingFillBand(Imaging imOut, int band, int color) {
 
     /* Check arguments */
     if (!imOut || imOut->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (band < 0 || band >= imOut->bands) {
@@ -270,11 +270,11 @@ ImagingMerge(const ModeID mode, Imaging bands[4]) {
             break;
         }
         if (bands[i]->bands != 1) {
-            return (Imaging)ImagingError_ModeError();
+            return (Imaging)ImagingError_ModeError(NULL);
         }
         if (bands[i]->xsize != firstBand->xsize ||
             bands[i]->ysize != firstBand->ysize) {
-            return (Imaging)ImagingError_Mismatch();
+            return (Imaging)ImagingError_Mismatch(NULL);
         }
     }
     bandsCount = i;
diff --git a/src/libImaging/Blend.c b/src/libImaging/Blend.c
index 19662abf044..e2a8b9cf89d 100644
--- a/src/libImaging/Blend.c
+++ b/src/libImaging/Blend.c
@@ -26,12 +26,12 @@ ImagingBlend(Imaging imIn1, Imaging imIn2, float alpha) {
     if (!imIn1 || !imIn2 || imIn1->type != IMAGING_TYPE_UINT8 || imIn1->palette ||
         imIn1->mode == IMAGING_MODE_1 || imIn2->palette ||
         imIn2->mode == IMAGING_MODE_1) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     if (imIn1->type != imIn2->type || imIn1->bands != imIn2->bands ||
         imIn1->xsize != imIn2->xsize || imIn1->ysize != imIn2->ysize) {
-        return ImagingError_Mismatch();
+        return ImagingError_Mismatch(NULL);
     }
 
     /* Shortcuts */
diff --git a/src/libImaging/BoxBlur.c b/src/libImaging/BoxBlur.c
index 4fea4fe44b8..c94b1115e05 100644
--- a/src/libImaging/BoxBlur.c
+++ b/src/libImaging/BoxBlur.c
@@ -251,18 +251,18 @@ ImagingBoxBlur(Imaging imOut, Imaging imIn, float xradius, float yradius, int n)
     if (imIn->mode != imOut->mode || imIn->type != imOut->type ||
         imIn->bands != imOut->bands || imIn->xsize != imOut->xsize ||
         imIn->ysize != imOut->ysize) {
-        return ImagingError_Mismatch();
+        return ImagingError_Mismatch(NULL);
     }
 
     if (imIn->type != IMAGING_TYPE_UINT8) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     if (imIn->mode != IMAGING_MODE_RGB && imIn->mode != IMAGING_MODE_RGBA &&
         imIn->mode != IMAGING_MODE_RGBa && imIn->mode != IMAGING_MODE_RGBX &&
         imIn->mode != IMAGING_MODE_CMYK && imIn->mode != IMAGING_MODE_L &&
         imIn->mode != IMAGING_MODE_LA && imIn->mode != IMAGING_MODE_La) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     /* Apply blur in one dimension.
diff --git a/src/libImaging/Chops.c b/src/libImaging/Chops.c
index 557c2f52f10..d9f494c70d5 100644
--- a/src/libImaging/Chops.c
+++ b/src/libImaging/Chops.c
@@ -72,10 +72,10 @@ create(Imaging im1, Imaging im2, const ModeID mode) {
     if (!im1 || !im2 || im1->type != IMAGING_TYPE_UINT8 ||
         (mode != IMAGING_MODE_UNKNOWN &&
          (im1->mode != IMAGING_MODE_1 || im2->mode != IMAGING_MODE_1))) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (im1->type != im2->type || im1->bands != im2->bands) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     xsize = (im1->xsize < im2->xsize) ? im1->xsize : im2->xsize;
diff --git a/src/libImaging/ColorLUT.c b/src/libImaging/ColorLUT.c
index 5559de689b2..9c7829b3592 100644
--- a/src/libImaging/ColorLUT.c
+++ b/src/libImaging/ColorLUT.c
@@ -89,12 +89,12 @@ ImagingColorLUT3D_linear(
 
     if (imIn->type != IMAGING_TYPE_UINT8 || imOut->type != IMAGING_TYPE_UINT8 ||
         imIn->bands < 3 || imOut->bands < table_channels) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     /* In case we have one extra band in imOut and don't have in imIn.*/
     if (imOut->bands > table_channels && imOut->bands > imIn->bands) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     ImagingSectionEnter(&cookie);
diff --git a/src/libImaging/Convert.c b/src/libImaging/Convert.c
index 1fd14a944ef..f2a5e7912c7 100644
--- a/src/libImaging/Convert.c
+++ b/src/libImaging/Convert.c
@@ -1581,13 +1581,13 @@ convert(Imaging imOut, Imaging imIn, ModeID mode, ImagingPalette palette, int di
     ImagingShuffler convert;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (mode == IMAGING_MODE_UNKNOWN) {
         /* Map palette image to full depth */
         if (!imIn->palette) {
-            return (Imaging)ImagingError_ModeError();
+            return (Imaging)ImagingError_ModeError(NULL);
         }
         mode = imIn->palette->mode;
     } else {
@@ -1673,7 +1673,7 @@ ImagingConvertTransparent(Imaging imIn, const ModeID mode, int r, int g, int b)
     int y;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (imIn->mode == IMAGING_MODE_RGB &&
@@ -1747,7 +1747,7 @@ ImagingConvertInPlace(Imaging imIn, const ModeID mode) {
     } else if (imIn->mode == IMAGING_MODE_1 && mode == IMAGING_MODE_L) {
         convert = bit2l;
     } else {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     ImagingSectionEnter(&cookie);
diff --git a/src/libImaging/Crop.c b/src/libImaging/Crop.c
index 2425b4cd589..7bbdc86c474 100644
--- a/src/libImaging/Crop.c
+++ b/src/libImaging/Crop.c
@@ -25,7 +25,7 @@ ImagingCrop(Imaging imIn, int sx0, int sy0, int sx1, int sy1) {
     INT32 zero = 0;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     xsize = sx1 - sx0;
diff --git a/src/libImaging/Dib.c b/src/libImaging/Dib.c
index 2afe71d4ac9..2624f4c3d22 100644
--- a/src/libImaging/Dib.c
+++ b/src/libImaging/Dib.c
@@ -59,7 +59,7 @@ ImagingNewDIB(const ModeID mode, int xsize, int ysize) {
 
     /* Check mode */
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_L && mode != IMAGING_MODE_RGB) {
-        return (ImagingDIB)ImagingError_ModeError();
+        return (ImagingDIB)ImagingError_ModeError(NULL);
     }
 
     const int pixelsize = mode == IMAGING_MODE_RGB ? 3 : 1;
diff --git a/src/libImaging/Fill.c b/src/libImaging/Fill.c
index 25344cf3a7e..486c54ecdfb 100644
--- a/src/libImaging/Fill.c
+++ b/src/libImaging/Fill.c
@@ -78,7 +78,7 @@ ImagingFillLinearGradient(const ModeID mode) {
 
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_F && mode != IMAGING_MODE_I &&
         mode != IMAGING_MODE_L && mode != IMAGING_MODE_P) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     im = ImagingNewDirty(mode, 256, 256);
@@ -117,7 +117,7 @@ ImagingFillRadialGradient(const ModeID mode) {
 
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_F && mode != IMAGING_MODE_I &&
         mode != IMAGING_MODE_L && mode != IMAGING_MODE_P) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     im = ImagingNewDirty(mode, 256, 256);
diff --git a/src/libImaging/Filter.c b/src/libImaging/Filter.c
index b5f971d40c2..349a030234b 100644
--- a/src/libImaging/Filter.c
+++ b/src/libImaging/Filter.c
@@ -472,7 +472,7 @@ ImagingFilter(Imaging im, int xsize, int ysize, const FLOAT32 *kernel, FLOAT32 o
 
     if (im->type == IMAGING_TYPE_FLOAT32 ||
         (im->type == IMAGING_TYPE_SPECIAL && im->bands != 1)) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (im->xsize < xsize || im->ysize < ysize) {
diff --git a/src/libImaging/Geometry.c b/src/libImaging/Geometry.c
index 2186f95f8e5..659e63948c2 100644
--- a/src/libImaging/Geometry.c
+++ b/src/libImaging/Geometry.c
@@ -20,10 +20,10 @@ ImagingFlipLeftRight(Imaging imOut, Imaging imIn) {
     int x, y, xr;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -63,10 +63,10 @@ ImagingFlipTopBottom(Imaging imOut, Imaging imIn) {
     int y, yr;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -90,10 +90,10 @@ ImagingRotate90(Imaging imOut, Imaging imIn) {
     int xxx, yyy, xxxsize, yyysize;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -150,10 +150,10 @@ ImagingTranspose(Imaging imOut, Imaging imIn) {
     int xxx, yyy, xxxsize, yyysize;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -209,10 +209,10 @@ ImagingTransverse(Imaging imOut, Imaging imIn) {
     int xxx, yyy, xxxsize, yyysize;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -269,10 +269,10 @@ ImagingRotate180(Imaging imOut, Imaging imIn) {
     int x, y, xr, yr;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -314,10 +314,10 @@ ImagingRotate270(Imaging imOut, Imaging imIn) {
     int xxx, yyy, xxxsize, yyysize;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch();
+        return (Imaging)ImagingError_Mismatch(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -785,7 +785,7 @@ ImagingGenericTransform(
     double xx, yy;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     ImagingTransformFilter filter = getfilter(imIn, filterid);
@@ -842,7 +842,7 @@ ImagingScaleAffine(
     int *xintab;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -1029,7 +1029,7 @@ ImagingTransformAffine(
     double xo, yo;
 
     if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (filterid || imIn->type == IMAGING_TYPE_SPECIAL) {
diff --git a/src/libImaging/GetBBox.c b/src/libImaging/GetBBox.c
index 7a57f6894a0..1ffe1c76566 100644
--- a/src/libImaging/GetBBox.c
+++ b/src/libImaging/GetBBox.c
@@ -152,7 +152,7 @@ ImagingGetExtrema(Imaging im, void *extrema) {
     FLOAT32 fmin, fmax;
 
     if (im->bands != 1) {
-        (void)ImagingError_ModeError();
+        (void)ImagingError_ModeError(NULL);
         return -1; /* mismatch */
     }
 
@@ -242,7 +242,7 @@ ImagingGetExtrema(Imaging im, void *extrema) {
             }
             /* FALL THROUGH */
         default:
-            (void)ImagingError_ModeError();
+            (void)ImagingError_ModeError(NULL);
             return -1;
     }
     return 1; /* ok */
@@ -304,7 +304,7 @@ getcolors32(Imaging im, int maxcolors, int *size) {
     }
 
     if (!im->image32) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     table = calloc(code_size + 1, sizeof(ImagingColorItem));
diff --git a/src/libImaging/Histo.c b/src/libImaging/Histo.c
index 7af60003511..e32b17f2ded 100644
--- a/src/libImaging/Histo.c
+++ b/src/libImaging/Histo.c
@@ -65,13 +65,13 @@ ImagingGetHistogram(Imaging im, Imaging imMask, void *minmax) {
     FLOAT32 fmin, fmax, scale;
 
     if (!im) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     if (imMask) {
         /* Validate mask */
         if (im->xsize != imMask->xsize || im->ysize != imMask->ysize) {
-            return ImagingError_Mismatch();
+            return ImagingError_Mismatch(NULL);
         }
         if (imMask->mode != IMAGING_MODE_1 && imMask->mode != IMAGING_MODE_L) {
             return ImagingError_ValueError("bad transparency mask");
@@ -98,7 +98,7 @@ ImagingGetHistogram(Imaging im, Imaging imMask, void *minmax) {
         } else { /* yes, we need the braces. C isn't Python! */
             if (im->type != IMAGING_TYPE_UINT8) {
                 ImagingHistogramDelete(h);
-                return ImagingError_ModeError();
+                return ImagingError_ModeError(NULL);
             }
             ImagingSectionEnter(&cookie);
             for (y = 0; y < im->ysize; y++) {
diff --git a/src/libImaging/Imaging.h b/src/libImaging/Imaging.h
index 00c148f5d60..3a2cafaa39b 100644
--- a/src/libImaging/Imaging.h
+++ b/src/libImaging/Imaging.h
@@ -268,9 +268,9 @@ ImagingSectionLeave(ImagingSectionCookie *cookie);
 extern void *
 ImagingError_MemoryError(void);
 extern void *
-ImagingError_ModeError(void); /* maps to ValueError by default */
+ImagingError_ModeError(const char *message); /* maps to ValueError by default */
 extern void *
-ImagingError_Mismatch(void); /* maps to ValueError by default */
+ImagingError_Mismatch(const char *message); /* maps to ValueError by default */
 extern void *
 ImagingError_ValueError(const char *message);
 extern void *
diff --git a/src/libImaging/Matrix.c b/src/libImaging/Matrix.c
index 02676c9e31a..be2aaa10f02 100644
--- a/src/libImaging/Matrix.c
+++ b/src/libImaging/Matrix.c
@@ -24,7 +24,7 @@ ImagingConvertMatrix(Imaging im, const ModeID mode, const float m[12]) {
 
     /* Assume there's enough data in the buffer */
     if (!im || im->bands != 3) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (mode == IMAGING_MODE_L) {
@@ -77,7 +77,7 @@ ImagingConvertMatrix(Imaging im, const ModeID mode, const float m[12]) {
             ImagingSectionLeave(&cookie);
         }
     } else {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     return imOut;
diff --git a/src/libImaging/ModeFilter.c b/src/libImaging/ModeFilter.c
index 757cbc3fb86..018c6e61460 100644
--- a/src/libImaging/ModeFilter.c
+++ b/src/libImaging/ModeFilter.c
@@ -25,7 +25,7 @@ ImagingModeFilter(Imaging im, int size) {
     int histogram[256];
 
     if (!im || im->bands != 1 || im->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
diff --git a/src/libImaging/Negative.c b/src/libImaging/Negative.c
index 114e8608e87..d6e873964b3 100644
--- a/src/libImaging/Negative.c
+++ b/src/libImaging/Negative.c
@@ -24,7 +24,7 @@ ImagingNegative(Imaging im) {
     int x, y;
 
     if (!im) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
diff --git a/src/libImaging/Offset.c b/src/libImaging/Offset.c
index 91ee91083cc..dc77db01051 100644
--- a/src/libImaging/Offset.c
+++ b/src/libImaging/Offset.c
@@ -22,7 +22,7 @@ ImagingOffset(Imaging im, int xoffset, int yoffset) {
     Imaging imOut;
 
     if (!im) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
diff --git a/src/libImaging/Palette.c b/src/libImaging/Palette.c
index b2dacf656b5..a4a5a64b27d 100644
--- a/src/libImaging/Palette.c
+++ b/src/libImaging/Palette.c
@@ -29,7 +29,7 @@ ImagingPaletteNew(const ModeID mode) {
 
     if (mode != IMAGING_MODE_RGB && mode != IMAGING_MODE_RGBA &&
         mode != IMAGING_MODE_CMYK) {
-        return (ImagingPalette)ImagingError_ModeError();
+        return (ImagingPalette)ImagingError_ModeError(NULL);
     }
 
     palette = calloc(1, sizeof(struct ImagingPaletteInstance));
diff --git a/src/libImaging/Paste.c b/src/libImaging/Paste.c
index 0396cf58095..3c045ab9c7f 100644
--- a/src/libImaging/Paste.c
+++ b/src/libImaging/Paste.c
@@ -280,7 +280,7 @@ ImagingPaste(
     ImagingSectionCookie cookie;
 
     if (!imOut || !imIn) {
-        (void)ImagingError_ModeError();
+        (void)ImagingError_ModeError(NULL);
         return -1;
     }
 
@@ -290,12 +290,12 @@ ImagingPaste(
     ysize = (int64_t)dy1 - dy0;
 
     if (xsize != imIn->xsize || ysize != imIn->ysize || pixelsize != imIn->pixelsize) {
-        (void)ImagingError_Mismatch();
+        (void)ImagingError_Mismatch(NULL);
         return -1;
     }
 
     if (imMask && (xsize != imMask->xsize || ysize != imMask->ysize)) {
-        (void)ImagingError_Mismatch();
+        (void)ImagingError_Mismatch(NULL);
         return -1;
     }
 
@@ -603,7 +603,7 @@ ImagingFill2(
     int sx0, sy0;
 
     if (!imOut || !ink) {
-        (void)ImagingError_ModeError();
+        (void)ImagingError_ModeError(NULL);
         return -1;
     }
 
@@ -613,7 +613,7 @@ ImagingFill2(
     ysize = (int64_t)dy1 - dy0;
 
     if (imMask && (xsize != imMask->xsize || ysize != imMask->ysize)) {
-        (void)ImagingError_Mismatch();
+        (void)ImagingError_Mismatch(NULL);
         return -1;
     }
 
diff --git a/src/libImaging/Point.c b/src/libImaging/Point.c
index 8f6d47c770f..f29ea43fd6d 100644
--- a/src/libImaging/Point.c
+++ b/src/libImaging/Point.c
@@ -137,7 +137,7 @@ ImagingPoint(Imaging imIn, ModeID mode, const void *table) {
     void (*point)(Imaging imIn, Imaging imOut, im_point_context *context);
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (mode == IMAGING_MODE_UNKNOWN) {
@@ -212,7 +212,7 @@ ImagingPointTransform(Imaging imIn, double scale, double offset) {
 
     if (!imIn || (imIn->mode != IMAGING_MODE_I && imIn->mode != IMAGING_MODE_I_16 &&
                   imIn->mode != IMAGING_MODE_F)) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     imOut = ImagingNew(imIn->mode, imIn->xsize, imIn->ysize);
diff --git a/src/libImaging/Quant.c b/src/libImaging/Quant.c
index 99c2dbac3af..936309b047f 100644
--- a/src/libImaging/Quant.c
+++ b/src/libImaging/Quant.c
@@ -1678,7 +1678,7 @@ ImagingQuantize(Imaging im, int colors, int mode, int kmeans) {
     ImagingSectionCookie cookie;
 
     if (!im) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
     if (colors < 1 || colors > 256) {
         /* FIXME: for colors > 256, consider returning an RGB image
@@ -1688,12 +1688,12 @@ ImagingQuantize(Imaging im, int colors, int mode, int kmeans) {
 
     if (im->mode != IMAGING_MODE_L && im->mode != IMAGING_MODE_P &&
         im->mode != IMAGING_MODE_RGB && im->mode != IMAGING_MODE_RGBA) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     /* only octree and imagequant supports RGBA */
     if (im->mode == IMAGING_MODE_RGBA && mode != 2 && mode != 3) {
-        return ImagingError_ModeError();
+        return ImagingError_ModeError(NULL);
     }
 
     // Hoisted here as these are invariant over the loops below.
diff --git a/src/libImaging/RankFilter.c b/src/libImaging/RankFilter.c
index 9b13b103283..13f500c525f 100644
--- a/src/libImaging/RankFilter.c
+++ b/src/libImaging/RankFilter.c
@@ -65,7 +65,7 @@ MakeRankFunction(UINT8) MakeRankFunction(INT32) MakeRankFunction(FLOAT32)
     int i, margin, size2;
 
     if (!im || im->bands != 1 || im->type == IMAGING_TYPE_SPECIAL) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (!(size & 1)) {
@@ -121,7 +121,7 @@ MakeRankFunction(UINT8) MakeRankFunction(INT32) MakeRankFunction(FLOAT32)
     } else {
         /* safety net (we shouldn't end up here) */
         ImagingDelete(imOut);
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     ImagingCopyPalette(imOut, im);
diff --git a/src/libImaging/Reduce.c b/src/libImaging/Reduce.c
index a4e58ced81b..659d4003c6d 100644
--- a/src/libImaging/Reduce.c
+++ b/src/libImaging/Reduce.c
@@ -1453,11 +1453,11 @@ ImagingReduce(Imaging imIn, int xscale, int yscale, int box[4]) {
     Imaging imOut = NULL;
 
     if (imIn->mode == IMAGING_MODE_P || imIn->mode == IMAGING_MODE_1) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (imIn->type == IMAGING_TYPE_SPECIAL) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     imOut = ImagingNewDirty(
diff --git a/src/libImaging/Resample.c b/src/libImaging/Resample.c
index c25383a70e4..db99d341488 100644
--- a/src/libImaging/Resample.c
+++ b/src/libImaging/Resample.c
@@ -714,7 +714,7 @@ ImagingResample(Imaging imIn, int xsize, int ysize, int filter, float box[4]) {
     ResampleFunction ResampleVertical;
 
     if (imIn->mode == IMAGING_MODE_P || imIn->mode == IMAGING_MODE_1) {
-        return (Imaging)ImagingError_ModeError();
+        return (Imaging)ImagingError_ModeError(NULL);
     }
 
     if (imIn->type == IMAGING_TYPE_SPECIAL) {
@@ -722,7 +722,7 @@ ImagingResample(Imaging imIn, int xsize, int ysize, int filter, float box[4]) {
             ResampleHorizontal = _ImagingResampleHorizontal_16bpc;
             ResampleVertical = _ImagingResampleVertical_16bpc;
         } else {
-            return (Imaging)ImagingError_ModeError();
+            return (Imaging)ImagingError_ModeError(NULL);
         }
     } else if (imIn->image8) {
         ResampleHorizontal = _ImagingResampleHorizontal_8bpc;
@@ -739,7 +739,7 @@ ImagingResample(Imaging imIn, int xsize, int ysize, int filter, float box[4]) {
                 ResampleVertical = _ImagingResampleVertical_32bpc;
                 break;
             default:
-                return (Imaging)ImagingError_ModeError();
+                return (Imaging)ImagingError_ModeError(NULL);
         }
     }
 
diff --git a/src/libImaging/Storage.c b/src/libImaging/Storage.c
index eae4c988f89..88e02175545 100644
--- a/src/libImaging/Storage.c
+++ b/src/libImaging/Storage.c
@@ -748,7 +748,7 @@ ImagingNew2Dirty(const ModeID mode, Imaging imOut, Imaging imIn) {
         /* make sure images match */
         if (imOut->mode != mode || imOut->xsize != imIn->xsize ||
             imOut->ysize != imIn->ysize) {
-            return ImagingError_Mismatch();
+            return ImagingError_Mismatch(NULL);
         }
     } else {
         /* create new image */

From 5d217b01c45e1cdd8e0702c388eb18c367b71ab8 Mon Sep 17 00:00:00 2001
From: Aarni Koskela <akx@iki.fi>
Date: Thu, 9 Jul 2026 10:48:23 +0300
Subject: [PATCH 4/5] Add bespoke error messages where suitable

---
 Tests/test_color_lut.py         |  2 +-
 Tests/test_image_paste.py       |  4 +-
 src/libImaging/AlphaComposite.c | 10 ++--
 src/libImaging/Bands.c          | 25 ++++++---
 src/libImaging/Blend.c          |  2 +-
 src/libImaging/BoxBlur.c        |  8 +--
 src/libImaging/Chops.c          |  2 +-
 src/libImaging/ColorLUT.c       | 21 +++++---
 src/libImaging/Convert.c        |  4 +-
 src/libImaging/Dib.c            |  4 +-
 src/libImaging/Effects.c        |  4 +-
 src/libImaging/Fill.c           |  8 ++-
 src/libImaging/Filter.c         |  4 +-
 src/libImaging/Geometry.c       | 92 +++++++++++++++++++++++----------
 src/libImaging/GetBBox.c        |  6 +--
 src/libImaging/Histo.c          |  2 +-
 src/libImaging/Matrix.c         |  7 ++-
 src/libImaging/ModeFilter.c     |  5 +-
 src/libImaging/Palette.c        |  4 +-
 src/libImaging/Paste.c          |  6 +--
 src/libImaging/Point.c          |  7 ++-
 src/libImaging/Quant.c          |  5 +-
 src/libImaging/Reduce.c         |  6 ++-
 src/libImaging/Resample.c       |  6 ++-
 src/libImaging/Storage.c        |  2 +-
 25 files changed, 167 insertions(+), 79 deletions(-)

diff --git a/Tests/test_color_lut.py b/Tests/test_color_lut.py
index 26945ae1a69..89a1e675c80 100644
--- a/Tests/test_color_lut.py
+++ b/Tests/test_color_lut.py
@@ -137,7 +137,7 @@ def test_correct_args(
     def test_wrong_mode(
         self, image_mode: str, lut_mode: str, table_channels: int, table_size: int
     ) -> None:
-        with pytest.raises(ValueError, match="wrong mode"):
+        with pytest.raises(ValueError, match="bands"):
             im = Image.new(image_mode, (10, 10), 0)
             im.im.color_lut_3d(
                 lut_mode,
diff --git a/Tests/test_image_paste.py b/Tests/test_image_paste.py
index f9b72e46fc8..e9211dae73e 100644
--- a/Tests/test_image_paste.py
+++ b/Tests/test_image_paste.py
@@ -368,7 +368,9 @@ def test_overflow(self, box: tuple[int, int, int, int]) -> None:
         im = Image.new("1", (1, 1))
         im.paste(1, box)
 
-        with pytest.raises(ValueError, match="images do not match"):
+        with pytest.raises(
+            ValueError, match="image dimensions and pixel size must match"
+        ):
             im.paste(im.copy(), box)
 
     def test_incorrect_abbreviated_form(self) -> None:
diff --git a/src/libImaging/AlphaComposite.c b/src/libImaging/AlphaComposite.c
index 0718e2ab1d7..a12f7398e66 100644
--- a/src/libImaging/AlphaComposite.c
+++ b/src/libImaging/AlphaComposite.c
@@ -24,14 +24,16 @@ ImagingAlphaComposite(Imaging imDst, Imaging imSrc) {
     Imaging imOut;
 
     /* Check arguments */
-    if (!imDst || !imSrc ||
-        (imDst->mode != IMAGING_MODE_RGBA && imDst->mode != IMAGING_MODE_LA)) {
-        return ImagingError_ModeError(NULL);
+    if (!imDst || !imSrc) {
+        return ImagingError_ValueError("imDst and imSrc must not be NULL");
+    }
+    if (imDst->mode != IMAGING_MODE_RGBA && imDst->mode != IMAGING_MODE_LA) {
+        return ImagingError_ModeError("destination image must have alpha channel");
     }
 
     if (imDst->mode != imSrc->mode || imDst->xsize != imSrc->xsize ||
         imDst->ysize != imSrc->ysize) {
-        return ImagingError_Mismatch(NULL);
+        return ImagingError_Mismatch("image modes and dimensions must match");
     }
 
     imOut = ImagingNewDirty(imDst->mode, imDst->xsize, imDst->ysize);
diff --git a/src/libImaging/Bands.c b/src/libImaging/Bands.c
index 53e15771bfb..9bc4e5a3a6a 100644
--- a/src/libImaging/Bands.c
+++ b/src/libImaging/Bands.c
@@ -24,7 +24,7 @@ ImagingGetBand(Imaging imIn, int band) {
 
     /* Check arguments */
     if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError(NULL);
     }
 
     if (band < 0 || band >= imIn->bands) {
@@ -74,7 +74,7 @@ ImagingSplit(Imaging imIn, Imaging bands[4]) {
 
     /* Check arguments */
     if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        (void)ImagingError_ModeError(NULL);
+        (void)ImagingError_NotSupportedError(NULL);
         return 0;
     }
 
@@ -178,9 +178,12 @@ ImagingPutBand(Imaging imOut, Imaging imIn, int band) {
     int x, y;
 
     /* Check arguments */
-    if (!imIn || imIn->bands != 1 || !imOut) {
+    if (!imIn || !imOut) {
         return (Imaging)ImagingError_ModeError(NULL);
     }
+    if (imIn->bands != 1) {
+        return (Imaging)ImagingError_ModeError("source image must have exactly 1 band");
+    }
 
     if (band < 0 || band >= imOut->bands) {
         return (Imaging)ImagingError_ValueError("band index out of range");
@@ -188,7 +191,7 @@ ImagingPutBand(Imaging imOut, Imaging imIn, int band) {
 
     if (imIn->type != imOut->type || imIn->xsize != imOut->xsize ||
         imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch("image types and sizes must match");
     }
 
     /* Shortcuts */
@@ -224,8 +227,12 @@ ImagingFillBand(Imaging imOut, int band, int color) {
     int x, y;
 
     /* Check arguments */
-    if (!imOut || imOut->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+
+    if (imOut->type != IMAGING_TYPE_UINT8) {
+        return (Imaging)ImagingError_NotSupportedError("only 8-bit images supported");
     }
 
     if (band < 0 || band >= imOut->bands) {
@@ -270,11 +277,13 @@ ImagingMerge(const ModeID mode, Imaging bands[4]) {
             break;
         }
         if (bands[i]->bands != 1) {
-            return (Imaging)ImagingError_ModeError(NULL);
+            return (Imaging)ImagingError_ModeError(
+                "source image must have exactly 1 band"
+            );
         }
         if (bands[i]->xsize != firstBand->xsize ||
             bands[i]->ysize != firstBand->ysize) {
-            return (Imaging)ImagingError_Mismatch(NULL);
+            return (Imaging)ImagingError_Mismatch("image sizes must match");
         }
     }
     bandsCount = i;
diff --git a/src/libImaging/Blend.c b/src/libImaging/Blend.c
index e2a8b9cf89d..70d809dfbaa 100644
--- a/src/libImaging/Blend.c
+++ b/src/libImaging/Blend.c
@@ -31,7 +31,7 @@ ImagingBlend(Imaging imIn1, Imaging imIn2, float alpha) {
 
     if (imIn1->type != imIn2->type || imIn1->bands != imIn2->bands ||
         imIn1->xsize != imIn2->xsize || imIn1->ysize != imIn2->ysize) {
-        return ImagingError_Mismatch(NULL);
+        return ImagingError_Mismatch("image types, band count and sizes must match");
     }
 
     /* Shortcuts */
diff --git a/src/libImaging/BoxBlur.c b/src/libImaging/BoxBlur.c
index c94b1115e05..7855085d092 100644
--- a/src/libImaging/BoxBlur.c
+++ b/src/libImaging/BoxBlur.c
@@ -251,18 +251,20 @@ ImagingBoxBlur(Imaging imOut, Imaging imIn, float xradius, float yradius, int n)
     if (imIn->mode != imOut->mode || imIn->type != imOut->type ||
         imIn->bands != imOut->bands || imIn->xsize != imOut->xsize ||
         imIn->ysize != imOut->ysize) {
-        return ImagingError_Mismatch(NULL);
+        return ImagingError_Mismatch("image mode, type, bands and size must match");
     }
 
     if (imIn->type != IMAGING_TYPE_UINT8) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_NotSupportedError("non-uint8 images not supported");
     }
 
     if (imIn->mode != IMAGING_MODE_RGB && imIn->mode != IMAGING_MODE_RGBA &&
         imIn->mode != IMAGING_MODE_RGBa && imIn->mode != IMAGING_MODE_RGBX &&
         imIn->mode != IMAGING_MODE_CMYK && imIn->mode != IMAGING_MODE_L &&
         imIn->mode != IMAGING_MODE_LA && imIn->mode != IMAGING_MODE_La) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_NotSupportedError(
+            "BoxBlur operation not supported in this mode"
+        );
     }
 
     /* Apply blur in one dimension.
diff --git a/src/libImaging/Chops.c b/src/libImaging/Chops.c
index d9f494c70d5..13c89ce9767 100644
--- a/src/libImaging/Chops.c
+++ b/src/libImaging/Chops.c
@@ -75,7 +75,7 @@ create(Imaging im1, Imaging im2, const ModeID mode) {
         return (Imaging)ImagingError_ModeError(NULL);
     }
     if (im1->type != im2->type || im1->bands != im2->bands) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch("image types and band count must match");
     }
 
     xsize = (im1->xsize < im2->xsize) ? im1->xsize : im2->xsize;
diff --git a/src/libImaging/ColorLUT.c b/src/libImaging/ColorLUT.c
index 9c7829b3592..572c5aad8f9 100644
--- a/src/libImaging/ColorLUT.c
+++ b/src/libImaging/ColorLUT.c
@@ -87,14 +87,23 @@ ImagingColorLUT3D_linear(
         return NULL;
     }
 
-    if (imIn->type != IMAGING_TYPE_UINT8 || imOut->type != IMAGING_TYPE_UINT8 ||
-        imIn->bands < 3 || imOut->bands < table_channels) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (imIn->type != IMAGING_TYPE_UINT8 || imOut->type != IMAGING_TYPE_UINT8) {
+        return (Imaging)ImagingError_NotSupportedError(
+            "only uint8 images are supported"
+        );
+    }
+    if (imIn->bands < 3) {
+        return (Imaging)ImagingError_ModeError("input image needs at least 3 bands");
+    }
+    if (imOut->bands < table_channels) {
+        return (Imaging)ImagingError_ValueError(
+            "output image needs at least as many bands as the table"
+        );
     }
-
-    /* In case we have one extra band in imOut and don't have in imIn.*/
     if (imOut->bands > table_channels && imOut->bands > imIn->bands) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ModeError(
+            "output image has more bands than input image and table"
+        );
     }
 
     ImagingSectionEnter(&cookie);
diff --git a/src/libImaging/Convert.c b/src/libImaging/Convert.c
index f2a5e7912c7..9c01505cd57 100644
--- a/src/libImaging/Convert.c
+++ b/src/libImaging/Convert.c
@@ -1747,7 +1747,9 @@ ImagingConvertInPlace(Imaging imIn, const ModeID mode) {
     } else if (imIn->mode == IMAGING_MODE_1 && mode == IMAGING_MODE_L) {
         convert = bit2l;
     } else {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_NotSupportedError(
+            "in-place conversion not supported between these formats"
+        );
     }
 
     ImagingSectionEnter(&cookie);
diff --git a/src/libImaging/Dib.c b/src/libImaging/Dib.c
index 2624f4c3d22..599f886ba30 100644
--- a/src/libImaging/Dib.c
+++ b/src/libImaging/Dib.c
@@ -59,7 +59,9 @@ ImagingNewDIB(const ModeID mode, int xsize, int ysize) {
 
     /* Check mode */
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_L && mode != IMAGING_MODE_RGB) {
-        return (ImagingDIB)ImagingError_ModeError(NULL);
+        return (ImagingDIB)ImagingError_NotSupportedError(
+            "only modes I/L/RGB supported"
+        );
     }
 
     const int pixelsize = mode == IMAGING_MODE_RGB ? 3 : 1;
diff --git a/src/libImaging/Effects.c b/src/libImaging/Effects.c
index c05c5764e44..181ad66893b 100644
--- a/src/libImaging/Effects.c
+++ b/src/libImaging/Effects.c
@@ -33,7 +33,9 @@ ImagingEffectMandelbrot(int xsize, int ysize, double extent[4], int quality) {
     width = extent[2] - extent[0];
     height = extent[3] - extent[1];
     if (width < 0.0 || height < 0.0 || quality < 2) {
-        return (Imaging)ImagingError_ValueError(NULL);
+        return (Imaging)ImagingError_ValueError(
+            "width and height must be positive and quality >= 2"
+        );
     }
 
     im = ImagingNewDirty(IMAGING_MODE_L, xsize, ysize);
diff --git a/src/libImaging/Fill.c b/src/libImaging/Fill.c
index 486c54ecdfb..0f63cd9aa67 100644
--- a/src/libImaging/Fill.c
+++ b/src/libImaging/Fill.c
@@ -78,7 +78,9 @@ ImagingFillLinearGradient(const ModeID mode) {
 
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_F && mode != IMAGING_MODE_I &&
         mode != IMAGING_MODE_L && mode != IMAGING_MODE_P) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError(
+            "only modes 1/F/I/L/P supported"
+        );
     }
 
     im = ImagingNewDirty(mode, 256, 256);
@@ -117,7 +119,9 @@ ImagingFillRadialGradient(const ModeID mode) {
 
     if (mode != IMAGING_MODE_1 && mode != IMAGING_MODE_F && mode != IMAGING_MODE_I &&
         mode != IMAGING_MODE_L && mode != IMAGING_MODE_P) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError(
+            "only modes 1/F/I/L/P supported"
+        );
     }
 
     im = ImagingNewDirty(mode, 256, 256);
diff --git a/src/libImaging/Filter.c b/src/libImaging/Filter.c
index 349a030234b..04077f890f2 100644
--- a/src/libImaging/Filter.c
+++ b/src/libImaging/Filter.c
@@ -472,7 +472,9 @@ ImagingFilter(Imaging im, int xsize, int ysize, const FLOAT32 *kernel, FLOAT32 o
 
     if (im->type == IMAGING_TYPE_FLOAT32 ||
         (im->type == IMAGING_TYPE_SPECIAL && im->bands != 1)) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ModeError(
+            "32-bpc or special multiband image types not supported"
+        );
     }
 
     if (im->xsize < xsize || im->ysize < ysize) {
diff --git a/src/libImaging/Geometry.c b/src/libImaging/Geometry.c
index 659e63948c2..e1ff00840ee 100644
--- a/src/libImaging/Geometry.c
+++ b/src/libImaging/Geometry.c
@@ -19,11 +19,14 @@ ImagingFlipLeftRight(Imaging imOut, Imaging imIn) {
     ImagingSectionCookie cookie;
     int x, y, xr;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch("images must have the same size");
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -62,11 +65,14 @@ ImagingFlipTopBottom(Imaging imOut, Imaging imIn) {
     ImagingSectionCookie cookie;
     int y, yr;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch("images must have the same size");
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -89,11 +95,16 @@ ImagingRotate90(Imaging imOut, Imaging imIn) {
     int x, y, xx, yy, xr, xxsize, yysize;
     int xxx, yyy, xxxsize, yyysize;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch(
+            "output size must be the transpose of the input size"
+        );
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -149,11 +160,16 @@ ImagingTranspose(Imaging imOut, Imaging imIn) {
     int x, y, xx, yy, xxsize, yysize;
     int xxx, yyy, xxxsize, yyysize;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch(
+            "output size must be the transpose of the input size"
+        );
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -208,11 +224,16 @@ ImagingTransverse(Imaging imOut, Imaging imIn) {
     int x, y, xr, yr, xx, yy, xxsize, yysize;
     int xxx, yyy, xxxsize, yyysize;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch(
+            "output size must be the transpose of the input size"
+        );
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -268,11 +289,14 @@ ImagingRotate180(Imaging imOut, Imaging imIn) {
     ImagingSectionCookie cookie;
     int x, y, xr, yr;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->xsize || imIn->ysize != imOut->ysize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch("images must have the same size");
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -313,11 +337,16 @@ ImagingRotate270(Imaging imOut, Imaging imIn) {
     int x, y, xx, yy, yr, xxsize, yysize;
     int xxx, yyy, xxxsize, yyysize;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
     if (imIn->xsize != imOut->ysize || imIn->ysize != imOut->xsize) {
-        return (Imaging)ImagingError_Mismatch(NULL);
+        return (Imaging)ImagingError_Mismatch(
+            "output size must be the transpose of the input size"
+        );
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -784,8 +813,11 @@ ImagingGenericTransform(
     char *out;
     double xx, yy;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
 
     ImagingTransformFilter filter = getfilter(imIn, filterid);
@@ -841,8 +873,11 @@ ImagingScaleAffine(
     int xmin, xmax;
     int *xintab;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
 
     ImagingCopyPalette(imOut, imIn);
@@ -1028,8 +1063,11 @@ ImagingTransformAffine(
     double xx, yy;
     double xo, yo;
 
-    if (!imOut || !imIn || imIn->mode != imOut->mode) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!imOut || !imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn->mode != imOut->mode) {
+        return (Imaging)ImagingError_ModeError("images must have the same mode");
     }
 
     if (filterid || imIn->type == IMAGING_TYPE_SPECIAL) {
diff --git a/src/libImaging/GetBBox.c b/src/libImaging/GetBBox.c
index 1ffe1c76566..f11ba6d1d6b 100644
--- a/src/libImaging/GetBBox.c
+++ b/src/libImaging/GetBBox.c
@@ -152,7 +152,7 @@ ImagingGetExtrema(Imaging im, void *extrema) {
     FLOAT32 fmin, fmax;
 
     if (im->bands != 1) {
-        (void)ImagingError_ModeError(NULL);
+        (void)ImagingError_ModeError("image must have exactly 1 band");
         return -1; /* mismatch */
     }
 
@@ -242,7 +242,7 @@ ImagingGetExtrema(Imaging im, void *extrema) {
             }
             /* FALL THROUGH */
         default:
-            (void)ImagingError_ModeError(NULL);
+            (void)ImagingError_NotSupportedError("mode not supported");
             return -1;
     }
     return 1; /* ok */
@@ -304,7 +304,7 @@ getcolors32(Imaging im, int maxcolors, int *size) {
     }
 
     if (!im->image32) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_ModeError("image must have 32-bit data");
     }
 
     table = calloc(code_size + 1, sizeof(ImagingColorItem));
diff --git a/src/libImaging/Histo.c b/src/libImaging/Histo.c
index e32b17f2ded..bdbece894c3 100644
--- a/src/libImaging/Histo.c
+++ b/src/libImaging/Histo.c
@@ -71,7 +71,7 @@ ImagingGetHistogram(Imaging im, Imaging imMask, void *minmax) {
     if (imMask) {
         /* Validate mask */
         if (im->xsize != imMask->xsize || im->ysize != imMask->ysize) {
-            return ImagingError_Mismatch(NULL);
+            return ImagingError_Mismatch("mask and image size must match");
         }
         if (imMask->mode != IMAGING_MODE_1 && imMask->mode != IMAGING_MODE_L) {
             return ImagingError_ValueError("bad transparency mask");
diff --git a/src/libImaging/Matrix.c b/src/libImaging/Matrix.c
index be2aaa10f02..5affeaba28d 100644
--- a/src/libImaging/Matrix.c
+++ b/src/libImaging/Matrix.c
@@ -23,9 +23,12 @@ ImagingConvertMatrix(Imaging im, const ModeID mode, const float m[12]) {
     ImagingSectionCookie cookie;
 
     /* Assume there's enough data in the buffer */
-    if (!im || im->bands != 3) {
+    if (!im) {
         return (Imaging)ImagingError_ModeError(NULL);
     }
+    if (im->bands != 3) {
+        return (Imaging)ImagingError_ModeError("image must have exactly 3 bands");
+    }
 
     if (mode == IMAGING_MODE_L) {
         imOut = ImagingNewDirty(IMAGING_MODE_L, im->xsize, im->ysize);
@@ -77,7 +80,7 @@ ImagingConvertMatrix(Imaging im, const ModeID mode, const float m[12]) {
             ImagingSectionLeave(&cookie);
         }
     } else {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError(NULL);
     }
 
     return imOut;
diff --git a/src/libImaging/ModeFilter.c b/src/libImaging/ModeFilter.c
index 018c6e61460..e6b1e540442 100644
--- a/src/libImaging/ModeFilter.c
+++ b/src/libImaging/ModeFilter.c
@@ -24,9 +24,12 @@ ImagingModeFilter(Imaging im, int size) {
     UINT8 maxpixel;
     int histogram[256];
 
-    if (!im || im->bands != 1 || im->type != IMAGING_TYPE_UINT8) {
+    if (!im) {
         return (Imaging)ImagingError_ModeError(NULL);
     }
+    if (im->bands != 1 || im->type != IMAGING_TYPE_UINT8) {
+        return (Imaging)ImagingError_ModeError("image must have 8-bit data in 1 band");
+    }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
     if (!imOut) {
diff --git a/src/libImaging/Palette.c b/src/libImaging/Palette.c
index a4a5a64b27d..4d7791b8aab 100644
--- a/src/libImaging/Palette.c
+++ b/src/libImaging/Palette.c
@@ -29,7 +29,9 @@ ImagingPaletteNew(const ModeID mode) {
 
     if (mode != IMAGING_MODE_RGB && mode != IMAGING_MODE_RGBA &&
         mode != IMAGING_MODE_CMYK) {
-        return (ImagingPalette)ImagingError_ModeError(NULL);
+        return (ImagingPalette)ImagingError_ModeError(
+            "only RGB/RGBA/CMYK images supported"
+        );
     }
 
     palette = calloc(1, sizeof(struct ImagingPaletteInstance));
diff --git a/src/libImaging/Paste.c b/src/libImaging/Paste.c
index 3c045ab9c7f..0a33a63eac9 100644
--- a/src/libImaging/Paste.c
+++ b/src/libImaging/Paste.c
@@ -290,12 +290,12 @@ ImagingPaste(
     ysize = (int64_t)dy1 - dy0;
 
     if (xsize != imIn->xsize || ysize != imIn->ysize || pixelsize != imIn->pixelsize) {
-        (void)ImagingError_Mismatch(NULL);
+        (void)ImagingError_Mismatch("image dimensions and pixel size must match");
         return -1;
     }
 
     if (imMask && (xsize != imMask->xsize || ysize != imMask->ysize)) {
-        (void)ImagingError_Mismatch(NULL);
+        (void)ImagingError_Mismatch("mask size must match image size");
         return -1;
     }
 
@@ -613,7 +613,7 @@ ImagingFill2(
     ysize = (int64_t)dy1 - dy0;
 
     if (imMask && (xsize != imMask->xsize || ysize != imMask->ysize)) {
-        (void)ImagingError_Mismatch(NULL);
+        (void)ImagingError_Mismatch("mask size must match image size");
         return -1;
     }
 
diff --git a/src/libImaging/Point.c b/src/libImaging/Point.c
index f29ea43fd6d..cf3691a9eb2 100644
--- a/src/libImaging/Point.c
+++ b/src/libImaging/Point.c
@@ -210,10 +210,13 @@ ImagingPointTransform(Imaging imIn, double scale, double offset) {
     Imaging imOut;
     int x, y;
 
-    if (!imIn || (imIn->mode != IMAGING_MODE_I && imIn->mode != IMAGING_MODE_I_16 &&
-                  imIn->mode != IMAGING_MODE_F)) {
+    if (!imIn) {
         return (Imaging)ImagingError_ModeError(NULL);
     }
+    if (imIn->mode != IMAGING_MODE_I && imIn->mode != IMAGING_MODE_I_16 &&
+        imIn->mode != IMAGING_MODE_F) {
+        return (Imaging)ImagingError_NotSupportedError("only modes I/I;16/F supported");
+    }
 
     imOut = ImagingNew(imIn->mode, imIn->xsize, imIn->ysize);
     if (!imOut) {
diff --git a/src/libImaging/Quant.c b/src/libImaging/Quant.c
index 936309b047f..7beff3f3aec 100644
--- a/src/libImaging/Quant.c
+++ b/src/libImaging/Quant.c
@@ -1688,12 +1688,11 @@ ImagingQuantize(Imaging im, int colors, int mode, int kmeans) {
 
     if (im->mode != IMAGING_MODE_L && im->mode != IMAGING_MODE_P &&
         im->mode != IMAGING_MODE_RGB && im->mode != IMAGING_MODE_RGBA) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_NotSupportedError("only modes L/P/RGB/RGBA supported");
     }
 
-    /* only octree and imagequant supports RGBA */
     if (im->mode == IMAGING_MODE_RGBA && mode != 2 && mode != 3) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_ModeError("only octree and imagequant support RGBA");
     }
 
     // Hoisted here as these are invariant over the loops below.
diff --git a/src/libImaging/Reduce.c b/src/libImaging/Reduce.c
index 659d4003c6d..1cd6e3ef7a6 100644
--- a/src/libImaging/Reduce.c
+++ b/src/libImaging/Reduce.c
@@ -1453,11 +1453,13 @@ ImagingReduce(Imaging imIn, int xscale, int yscale, int box[4]) {
     Imaging imOut = NULL;
 
     if (imIn->mode == IMAGING_MODE_P || imIn->mode == IMAGING_MODE_1) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError("only modes P/1 supported");
     }
 
     if (imIn->type == IMAGING_TYPE_SPECIAL) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError(
+            "special image types not supported"
+        );
     }
 
     imOut = ImagingNewDirty(
diff --git a/src/libImaging/Resample.c b/src/libImaging/Resample.c
index db99d341488..91c5df6c2a2 100644
--- a/src/libImaging/Resample.c
+++ b/src/libImaging/Resample.c
@@ -714,7 +714,7 @@ ImagingResample(Imaging imIn, int xsize, int ysize, int filter, float box[4]) {
     ResampleFunction ResampleVertical;
 
     if (imIn->mode == IMAGING_MODE_P || imIn->mode == IMAGING_MODE_1) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_NotSupportedError("only modes P/1 supported");
     }
 
     if (imIn->type == IMAGING_TYPE_SPECIAL) {
@@ -722,7 +722,9 @@ ImagingResample(Imaging imIn, int xsize, int ysize, int filter, float box[4]) {
             ResampleHorizontal = _ImagingResampleHorizontal_16bpc;
             ResampleVertical = _ImagingResampleVertical_16bpc;
         } else {
-            return (Imaging)ImagingError_ModeError(NULL);
+            return (Imaging)ImagingError_NotSupportedError(
+                "special image type not supported"
+            );
         }
     } else if (imIn->image8) {
         ResampleHorizontal = _ImagingResampleHorizontal_8bpc;
diff --git a/src/libImaging/Storage.c b/src/libImaging/Storage.c
index 88e02175545..ebe59dd8a77 100644
--- a/src/libImaging/Storage.c
+++ b/src/libImaging/Storage.c
@@ -748,7 +748,7 @@ ImagingNew2Dirty(const ModeID mode, Imaging imOut, Imaging imIn) {
         /* make sure images match */
         if (imOut->mode != mode || imOut->xsize != imIn->xsize ||
             imOut->ysize != imIn->ysize) {
-            return ImagingError_Mismatch(NULL);
+            return ImagingError_Mismatch("image modes and dimensions must match");
         }
     } else {
         /* create new image */

From 573fae6c40c7371d9e48984d4666f51bbe5990a3 Mon Sep 17 00:00:00 2001
From: Aarni Koskela <akx@iki.fi>
Date: Thu, 9 Jul 2026 11:03:29 +0300
Subject: [PATCH 5/5] Make sure image nullness checks raise ValueErrors, not
 ModeErrors

---
 src/libImaging/Bands.c      | 23 ++++++++++++++++++-----
 src/libImaging/Blend.c      |  5 ++++-
 src/libImaging/Chops.c      |  5 ++++-
 src/libImaging/Convert.c    |  4 ++--
 src/libImaging/Crop.c       |  2 +-
 src/libImaging/Histo.c      |  2 +-
 src/libImaging/Matrix.c     |  2 +-
 src/libImaging/ModeFilter.c |  2 +-
 src/libImaging/Negative.c   |  2 +-
 src/libImaging/Offset.c     |  2 +-
 src/libImaging/Paste.c      |  4 ++--
 src/libImaging/Point.c      |  4 ++--
 src/libImaging/Quant.c      |  2 +-
 src/libImaging/RankFilter.c | 10 ++++++++--
 14 files changed, 47 insertions(+), 22 deletions(-)

diff --git a/src/libImaging/Bands.c b/src/libImaging/Bands.c
index 9bc4e5a3a6a..29444b5168a 100644
--- a/src/libImaging/Bands.c
+++ b/src/libImaging/Bands.c
@@ -23,8 +23,12 @@ ImagingGetBand(Imaging imIn, int band) {
     int x, y;
 
     /* Check arguments */
-    if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        return (Imaging)ImagingError_NotSupportedError(NULL);
+    if (!imIn) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+
+    if (imIn->type != IMAGING_TYPE_UINT8) {
+        return (Imaging)ImagingError_NotSupportedError("only 8-bit images supported");
     }
 
     if (band < 0 || band >= imIn->bands) {
@@ -73,8 +77,13 @@ ImagingSplit(Imaging imIn, Imaging bands[4]) {
     int i, j, x, y;
 
     /* Check arguments */
-    if (!imIn || imIn->type != IMAGING_TYPE_UINT8) {
-        (void)ImagingError_NotSupportedError(NULL);
+    if (!imIn) {
+        (void)ImagingError_ValueError(NULL);
+        return 0;
+    }
+
+    if (imIn->type != IMAGING_TYPE_UINT8) {
+        (void)ImagingError_NotSupportedError("only 8-bit images supported");
         return 0;
     }
 
@@ -179,7 +188,7 @@ ImagingPutBand(Imaging imOut, Imaging imIn, int band) {
 
     /* Check arguments */
     if (!imIn || !imOut) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
     if (imIn->bands != 1) {
         return (Imaging)ImagingError_ModeError("source image must have exactly 1 band");
@@ -231,6 +240,10 @@ ImagingFillBand(Imaging imOut, int band, int color) {
         return (Imaging)ImagingError_ValueError(NULL);
     }
 
+    if (!imOut) {
+        return (Imaging)ImagingError_ValueError("only 8-bit images supported");
+    }
+
     if (imOut->type != IMAGING_TYPE_UINT8) {
         return (Imaging)ImagingError_NotSupportedError("only 8-bit images supported");
     }
diff --git a/src/libImaging/Blend.c b/src/libImaging/Blend.c
index 70d809dfbaa..5d849ba6619 100644
--- a/src/libImaging/Blend.c
+++ b/src/libImaging/Blend.c
@@ -23,7 +23,10 @@ ImagingBlend(Imaging imIn1, Imaging imIn2, float alpha) {
     int x, y;
 
     /* Check arguments */
-    if (!imIn1 || !imIn2 || imIn1->type != IMAGING_TYPE_UINT8 || imIn1->palette ||
+    if (!imIn1 || !imIn2) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+    if (imIn1->type != IMAGING_TYPE_UINT8 || imIn1->palette ||
         imIn1->mode == IMAGING_MODE_1 || imIn2->palette ||
         imIn2->mode == IMAGING_MODE_1) {
         return ImagingError_ModeError(NULL);
diff --git a/src/libImaging/Chops.c b/src/libImaging/Chops.c
index 13c89ce9767..d8e051fc988 100644
--- a/src/libImaging/Chops.c
+++ b/src/libImaging/Chops.c
@@ -68,8 +68,11 @@
 static Imaging
 create(Imaging im1, Imaging im2, const ModeID mode) {
     int xsize, ysize;
+    if (!im1 || !im2) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
 
-    if (!im1 || !im2 || im1->type != IMAGING_TYPE_UINT8 ||
+    if (im1->type != IMAGING_TYPE_UINT8 ||
         (mode != IMAGING_MODE_UNKNOWN &&
          (im1->mode != IMAGING_MODE_1 || im2->mode != IMAGING_MODE_1))) {
         return (Imaging)ImagingError_ModeError(NULL);
diff --git a/src/libImaging/Convert.c b/src/libImaging/Convert.c
index 9c01505cd57..f732dadbc01 100644
--- a/src/libImaging/Convert.c
+++ b/src/libImaging/Convert.c
@@ -1581,7 +1581,7 @@ convert(Imaging imOut, Imaging imIn, ModeID mode, ImagingPalette palette, int di
     ImagingShuffler convert;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     if (mode == IMAGING_MODE_UNKNOWN) {
@@ -1673,7 +1673,7 @@ ImagingConvertTransparent(Imaging imIn, const ModeID mode, int r, int g, int b)
     int y;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     if (imIn->mode == IMAGING_MODE_RGB &&
diff --git a/src/libImaging/Crop.c b/src/libImaging/Crop.c
index 7bbdc86c474..7379671fe86 100644
--- a/src/libImaging/Crop.c
+++ b/src/libImaging/Crop.c
@@ -25,7 +25,7 @@ ImagingCrop(Imaging imIn, int sx0, int sy0, int sx1, int sy1) {
     INT32 zero = 0;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     xsize = sx1 - sx0;
diff --git a/src/libImaging/Histo.c b/src/libImaging/Histo.c
index bdbece894c3..83fe4386c6c 100644
--- a/src/libImaging/Histo.c
+++ b/src/libImaging/Histo.c
@@ -65,7 +65,7 @@ ImagingGetHistogram(Imaging im, Imaging imMask, void *minmax) {
     FLOAT32 fmin, fmax, scale;
 
     if (!im) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_ValueError(NULL);
     }
 
     if (imMask) {
diff --git a/src/libImaging/Matrix.c b/src/libImaging/Matrix.c
index 5affeaba28d..2bcb7c789ae 100644
--- a/src/libImaging/Matrix.c
+++ b/src/libImaging/Matrix.c
@@ -24,7 +24,7 @@ ImagingConvertMatrix(Imaging im, const ModeID mode, const float m[12]) {
 
     /* Assume there's enough data in the buffer */
     if (!im) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
     if (im->bands != 3) {
         return (Imaging)ImagingError_ModeError("image must have exactly 3 bands");
diff --git a/src/libImaging/ModeFilter.c b/src/libImaging/ModeFilter.c
index e6b1e540442..99fed34c520 100644
--- a/src/libImaging/ModeFilter.c
+++ b/src/libImaging/ModeFilter.c
@@ -25,7 +25,7 @@ ImagingModeFilter(Imaging im, int size) {
     int histogram[256];
 
     if (!im) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
     if (im->bands != 1 || im->type != IMAGING_TYPE_UINT8) {
         return (Imaging)ImagingError_ModeError("image must have 8-bit data in 1 band");
diff --git a/src/libImaging/Negative.c b/src/libImaging/Negative.c
index d6e873964b3..f8acb7293b9 100644
--- a/src/libImaging/Negative.c
+++ b/src/libImaging/Negative.c
@@ -24,7 +24,7 @@ ImagingNegative(Imaging im) {
     int x, y;
 
     if (!im) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
diff --git a/src/libImaging/Offset.c b/src/libImaging/Offset.c
index dc77db01051..8802e4a0dc6 100644
--- a/src/libImaging/Offset.c
+++ b/src/libImaging/Offset.c
@@ -22,7 +22,7 @@ ImagingOffset(Imaging im, int xoffset, int yoffset) {
     Imaging imOut;
 
     if (!im) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     imOut = ImagingNewDirty(im->mode, im->xsize, im->ysize);
diff --git a/src/libImaging/Paste.c b/src/libImaging/Paste.c
index 0a33a63eac9..4c74b409659 100644
--- a/src/libImaging/Paste.c
+++ b/src/libImaging/Paste.c
@@ -280,7 +280,7 @@ ImagingPaste(
     ImagingSectionCookie cookie;
 
     if (!imOut || !imIn) {
-        (void)ImagingError_ModeError(NULL);
+        (void)ImagingError_ValueError(NULL);
         return -1;
     }
 
@@ -603,7 +603,7 @@ ImagingFill2(
     int sx0, sy0;
 
     if (!imOut || !ink) {
-        (void)ImagingError_ModeError(NULL);
+        (void)ImagingError_ValueError(NULL);
         return -1;
     }
 
diff --git a/src/libImaging/Point.c b/src/libImaging/Point.c
index cf3691a9eb2..e1abddfc4a1 100644
--- a/src/libImaging/Point.c
+++ b/src/libImaging/Point.c
@@ -137,7 +137,7 @@ ImagingPoint(Imaging imIn, ModeID mode, const void *table) {
     void (*point)(Imaging imIn, Imaging imOut, im_point_context *context);
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
 
     if (mode == IMAGING_MODE_UNKNOWN) {
@@ -211,7 +211,7 @@ ImagingPointTransform(Imaging imIn, double scale, double offset) {
     int x, y;
 
     if (!imIn) {
-        return (Imaging)ImagingError_ModeError(NULL);
+        return (Imaging)ImagingError_ValueError(NULL);
     }
     if (imIn->mode != IMAGING_MODE_I && imIn->mode != IMAGING_MODE_I_16 &&
         imIn->mode != IMAGING_MODE_F) {
diff --git a/src/libImaging/Quant.c b/src/libImaging/Quant.c
index 7beff3f3aec..0713018e208 100644
--- a/src/libImaging/Quant.c
+++ b/src/libImaging/Quant.c
@@ -1678,7 +1678,7 @@ ImagingQuantize(Imaging im, int colors, int mode, int kmeans) {
     ImagingSectionCookie cookie;
 
     if (!im) {
-        return ImagingError_ModeError(NULL);
+        return ImagingError_ValueError(NULL);
     }
     if (colors < 1 || colors > 256) {
         /* FIXME: for colors > 256, consider returning an RGB image
diff --git a/src/libImaging/RankFilter.c b/src/libImaging/RankFilter.c
index 13f500c525f..5ded6c61bbb 100644
--- a/src/libImaging/RankFilter.c
+++ b/src/libImaging/RankFilter.c
@@ -64,8 +64,14 @@ MakeRankFunction(UINT8) MakeRankFunction(INT32) MakeRankFunction(FLOAT32)
     int x, y;
     int i, margin, size2;
 
-    if (!im || im->bands != 1 || im->type == IMAGING_TYPE_SPECIAL) {
-        return (Imaging)ImagingError_ModeError(NULL);
+    if (!im) {
+        return (Imaging)ImagingError_ValueError(NULL);
+    }
+
+    if (im->bands != 1 || im->type == IMAGING_TYPE_SPECIAL) {
+        return (Imaging)ImagingError_ModeError(
+            "image must be 1-band non-special image"
+        );
     }
 
     if (!(size & 1)) {