jwtk/jjwt · error · io.jsonwebtoken.io.DeserializationException

Deserialized data is not a JSON Object; cannot create Map<St

Error message

Deserialized data is not a JSON Object; cannot create Map<String,?>

What it means

Thrown as a DeserializationException when the input deserializes successfully but is not a JSON object (e.g. a JSON array, string, or number), so it cannot be treated as Map<String,?>. JSON parsing in JJWT expects the top-level value to be an object.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/JsonObjectDeserializer.java:59

    public JsonObjectDeserializer(Deserializer<?> deserializer, String name) {
        this.deserializer = Assert.notNull(deserializer, "JSON Deserializer cannot be null.");
        this.name = Assert.hasText(name, "name cannot be null or empty.");
    }

    @Override
    public Map<String, ?> apply(Reader in) {
        Assert.notNull(in, "InputStream argument cannot be null.");
        Object value;
        try {
            value = this.deserializer.deserialize(in);
            if (value == null) {
                String msg = "Deserialized data resulted in a null value; cannot create Map<String,?>";
                throw new DeserializationException(msg);
            }
            if (!(value instanceof Map)) {
                String msg = "Deserialized data is not a JSON Object; cannot create Map<String,?>";
                throw new DeserializationException(msg);
            }
            // JSON Specification requires all JSON Objects to have string-only keys.  So instead of
            // checking that the val.keySet() has all Strings, we blindly cast to a Map<String,?>
            // since input would rarely, if ever, have non-string keys.
            //noinspection unchecked
            return (Map<String, ?>) value;
        } catch (StackOverflowError e) {
            String msg = String.format(MALFORMED_COMPLEX_ERROR, this.name, this.name, e.getMessage());
            throw new DeserializationException(msg, e);
        } catch (Throwable t) {
            throw malformed(t);
        }
    }

    protected RuntimeException malformed(Throwable t) {
        String msg = String.format(MALFORMED_ERROR, this.name, t.getMessage());
        throw new MalformedJwtException(msg, t);
    }

View on GitHub (pinned to fb71496164)

Solutions

Verify the input begins with '{' and is a valid JSON object at the top level.
If the data is a JSON array, wrap it in an object or deserialize it with a List-typed deserializer instead.
Check JWT parsing logic: ensure only the payload segment (not header or signature) is being deserialized as claims.
Log the raw input when debugging to see the actual top-level JSON structure.

Example fix

// before
byte[] payload = "[1,2,3]".getBytes(); // JSON array, not object
Map<String,?> claims = deserializer.deserialize(new ByteArrayInputStream(payload));
// after
byte[] payload = "{\"items\":[1,2,3]}".getBytes(); // wrap array in an object
Map<String,?> claims = deserializer.deserialize(new ByteArrayInputStream(payload));

Defensive patterns

Strategy: type-guard

Validate before calling

// Java
String s = new String(payload, StandardCharsets.UTF_8).trim();
if (!s.startsWith("{")) {
    throw new IllegalArgumentException("payload is not a JSON object");
}

Type guard

static boolean isJsonObjectPayload(byte[] bytes) {
    if (bytes == null || bytes.length == 0) return false;
    String s = new String(bytes, StandardCharsets.UTF_8).trim();
    return s.startsWith("{") && s.endsWith("}");
}

Try / catch

try {
    Map<String,?> claims = deserializer.apply(in);
} catch (DeserializationException e) {
    throw new IllegalArgumentException("Top-level JSON must be an object", e);
}

Prevention

Ensure JWT payloads are JSON objects, never bare arrays or scalars.
Split compact JWTs correctly — deserialize only the payload segment.
Validate the leading character of the payload before deserializing.
When handling arrays of claims, wrap them in a containing object.

When it happens

Trigger: Deserializing input whose top-level JSON value is an array ('[...]'), a bare string, number, or boolean rather than an object ('{...}').

Common situations: Passing a JWT payload that is a JSON array; feeding a JSON array body (e.g. a list of claims) where a claims object is required; concatenating or mis-splitting JWT segments so the wrong bytes are deserialized.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/a5afec79f978d1e3. Report an issue: GitHub.