json-path/JsonPath · error · MappingException

JSON integral number cannot be mapped to " + className

Error message

JSON integral number cannot be mapped to " + className

What it means

mapIntegralJsonNumber converts a JSON integral number to primitive wrappers/BigInteger/BigDecimal. If the target class is none of the supported numeric types (Byte..Long, BigInteger, BigDecimal), it throws MappingException with the simple class name. E.g. requesting Float for an integral number or a non-numeric type like String.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/mapper/JakartaMappingProvider.java:222

    private <T> T mapIntegralJsonNumber(JsonNumber jsonNumber, Class<?> targetType) {
        if (targetType.isPrimitive()) {
            if (int.class.equals(targetType)) {
                return (T) Integer.valueOf(jsonNumber.intValueExact());
            } else if (long.class.equals(targetType)) {
                return (T) Long.valueOf(jsonNumber.longValueExact());
            }
        } else if (Integer.class.equals(targetType)) {
            return (T) Integer.valueOf(jsonNumber.intValueExact());
        } else if (Long.class.equals(targetType)) {
            return (T) Long.valueOf(jsonNumber.longValueExact());
        } else if (BigInteger.class.equals(targetType)) {
            return (T) jsonNumber.bigIntegerValueExact();
        } else if (BigDecimal.class.equals(targetType)) {
            return (T) jsonNumber.bigDecimalValue();
        }

        String className = targetType.getSimpleName();
        throw new MappingException("JSON integral number cannot be mapped to " + className);
    }

    @SuppressWarnings("unchecked")
    private <T> T mapDecimalJsonNumber(JsonNumber jsonNumber, Class<?> targetType) {
        if (targetType.isPrimitive()) {
            if (float.class.equals(targetType)) {
                return (T) new Float(jsonNumber.doubleValue());
            } else if (double.class.equals(targetType)) {
                return (T) Double.valueOf(jsonNumber.doubleValue());
            }
        } else if (Float.class.equals(targetType)) {
            return (T) new Float(jsonNumber.doubleValue());
        } else if (Double.class.equals(targetType)) {
            return (T) Double.valueOf(jsonNumber.doubleValue());
        } else if (BigDecimal.class.equals(targetType)) {
            return (T) jsonNumber.bigDecimalValue();
        }

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Request one of the supported integral targets: Integer, Long, Short, Byte, BigInteger or BigDecimal
2. Request BigDecimal then convert (bd.floatValue(), bd.intValue())
3. Use .map(...) with a custom converter for unsupported target types
4. Change the path/document so the value matches the expected numeric type

Example fix

// before
Float f = ctx.read("$.count", Float.class); // 42 -> MappingException
// after
Float f = ctx.read("$.count", BigDecimal.class).floatValue();

Object raw = ctx.read(path);
if (!(raw instanceof Number)) throw new IllegalStateException(path + " is not numeric");
Integer n = ctx.read(path, Integer.class);

boolean isIntegralNumber(Object v) { return v instanceof Integer || v instanceof Long || v instanceof Short || v instanceof Byte || v instanceof BigInteger; }

try {
    Integer n = ctx.read(path, Integer.class);
} catch (MappingException e) {
    BigDecimal bd = ctx.read(path, BigDecimal.class);
    int n = bd.intValue();
}

When it happens

Trigger: read(path, Float.class) or read(path, String.class) where the JSON value is an integral number like 42; read(path, SomeEnum.class or Date.class) on an integral JSON number.

Common situations: Expecting numeric strings or dates to be produced from JSON integers; asking for Float/Double when the document contains an integer literal; type parameter mismatch where generics erase to an unexpected class.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• JSON decimal number cannot be mapped to " + className
• JSON boolean (false) cannot be mapped to " + className
• JSON string cannot be mapped to " + className
• InvalidJsonException
• InvalidJsonException

AI-assisted analysis of json-path/JsonPath@62a4c9f0f6 (2026-09-11). Data as JSON: /api/errors/335776ee82b98c46. Report an issue: GitHub.