Improve error messages for constructor argument mismatches

When constructor invocation fails with IllegalArgumentException, the
error diagnostic now:

1. Reports null-to-primitive issues: "null value for primitive double
   parameter 'ip_risk'" - this identifies the actual root cause when a
   database field is missing and the model uses a primitive type.

2. Uses proper type compatibility checks for boxed/primitive pairs.
   Previously, Boolean/boolean pairs were incorrectly reported as type
   mismatches even though auto-unboxing handles them correctly.

This makes debugging much easier by pointing to the actual problem
instead of reporting misleading type mismatches.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: oschwald

CHANGELOG.md

@@ -8,6 +8,9 @@ CHANGELOG
   `ConstructorNotFoundException` when the data was stored via a pointer
   in the database. This commonly occurred with deduplicated data in larger
   databases. Reported by Fabrice Bacchella. GitHub #644 in GeoIP2-java.
+* Improved error messages when constructor invocation fails. The error now
+  correctly identifies null values being passed to primitive parameters
+  instead of reporting misleading boxed/primitive type mismatches.
 
 4.0.1 (2025-12-02)
 ------------------

src/main/java/com/maxmind/db/Decoder.java

@@ -706,18 +706,68 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
             var sbErrors = new StringBuilder();
             for (var key : parameterIndexes.keySet()) {
                 var index = parameterIndexes.get(key);
-                if (parameters[index] != null
-                    && !parameters[index].getClass().isAssignableFrom(parameterTypes[index])) {
-                    sbErrors.append(" argument type mismatch in " + key + " MMDB Type: "
-                        + parameters[index].getClass().getCanonicalName()
-                        + " Java Type: " + parameterTypes[index].getCanonicalName());
+                if (parameters[index] == null && parameterTypes[index].isPrimitive()) {
+                    sbErrors.append(" null value for primitive ")
+                        .append(parameterTypes[index].getName())
+                        .append(" parameter '").append(key).append("'.");
+                } else if (parameters[index] != null
+                    && !isAssignableType(parameters[index].getClass(), parameterTypes[index])) {
+                    sbErrors.append(" argument type mismatch in ").append(key)
+                        .append(" MMDB Type: ")
+                        .append(parameters[index].getClass().getCanonicalName())
+                        .append(" Java Type: ")
+                        .append(parameterTypes[index].getCanonicalName())
+                        .append(".");
                 }
             }
             throw new DeserializationException(
-                "Error creating object of type: " + cls.getSimpleName() + " - " + sbErrors, e);
+                "Error creating object of type: " + cls.getSimpleName() + " -" + sbErrors, e);
         }
     }
 
+    /**
+     * Checks if an actual type can be assigned to an expected type,
+     * accounting for primitive/boxed equivalents (e.g., Boolean to boolean).
+     */
+    private static boolean isAssignableType(Class<?> actual, Class<?> expected) {
+        if (expected.isAssignableFrom(actual)) {
+            return true;
+        }
+        // Check primitive/boxed equivalents for auto-unboxing
+        if (expected.isPrimitive()) {
+            return actual.equals(boxedType(expected));
+        }
+        return false;
+    }
+
+    private static Class<?> boxedType(Class<?> primitive) {
+        if (primitive == boolean.class) {
+            return Boolean.class;
+        }
+        if (primitive == byte.class) {
+            return Byte.class;
+        }
+        if (primitive == short.class) {
+            return Short.class;
+        }
+        if (primitive == int.class) {
+            return Integer.class;
+        }
+        if (primitive == long.class) {
+            return Long.class;
+        }
+        if (primitive == float.class) {
+            return Float.class;
+        }
+        if (primitive == double.class) {
+            return Double.class;
+        }
+        if (primitive == char.class) {
+            return Character.class;
+        }
+        return primitive;
+    }
+
     private boolean shouldInstantiateFromContext(Class<?> parameterType) {
         if (parameterType == null
             || parameterType.isPrimitive()

src/test/java/com/maxmind/db/ReaderTest.java

@@ -2146,6 +2146,44 @@ public void testEnumCreatorWithPointerData(int chunkSize) throws IOException {
         }
     }
 
+    // Model class with primitive double field for testing null-to-primitive error messages
+    static class IpRiskModelWithPrimitive {
+        public final double ipRisk;
+
+        @MaxMindDbConstructor
+        public IpRiskModelWithPrimitive(
+            @MaxMindDbParameter(name = "ip_risk") double ipRisk
+        ) {
+            this.ipRisk = ipRisk;
+        }
+    }
+
+    /**
+     * Tests that error messages correctly report null-to-primitive issues instead of
+     * misleading boxed/primitive type mismatch messages.
+     *
+     * <p>IP 11.1.2.3 in the IP Risk test database doesn't have an ip_risk field.
+     * When deserializing to a model with a primitive double, the error message should
+     * correctly identify "null value for primitive double" rather than reporting
+     * misleading Boolean/boolean mismatches.
+     */
+    @ParameterizedTest
+    @MethodSource("chunkSizes")
+    public void testNullToPrimitiveErrorMessage(int chunkSize) throws IOException {
+        try (var reader = new Reader(getFile("GeoIP2-IP-Risk-Test.mmdb"), chunkSize)) {
+            var ip = InetAddress.getByName("11.1.2.3");
+
+            var exception = assertThrows(DeserializationException.class,
+                () -> reader.get(ip, IpRiskModelWithPrimitive.class));
+
+            // Error message should mention null value for primitive, not type mismatch
+            assertTrue(exception.getMessage().contains("null value for primitive double"),
+                "Error message should identify null-to-primitive issue: " + exception.getMessage());
+            assertTrue(exception.getMessage().contains("ip_risk"),
+                "Error message should name the problematic parameter: " + exception.getMessage());
+        }
+    }
+
     static File getFile(String name) {
         return new File(ReaderTest.class.getResource("/maxmind-db/test-data/" + name).getFile());
     }