eclipse-vertx/vert.x · error · DecodeException
Failed to decode
Error message
Failed to decode
What it means
JSON decoding failure surfaced by JacksonCodec.cast (via fromParser): the parsed JSON tree could not be converted to the requested target type (e.g. expecting a JsonObject/JsonArray but the JSON is a scalar or mismatched structure). The message 'Failed to decode' is a generic sentinel; the input at fault is the JSON payload versus the expected type.
Source
Thrown at vertx-core/src/main/java/io/vertx/core/json/jackson/JacksonCodec.java:512
} else if (json instanceof Float) {
generator.writeNumber((Float) json);
} else if (json instanceof Double) {
generator.writeNumber((Double) json);
} else if (json instanceof Byte) {
generator.writeNumber((Byte) json);
} else if (json instanceof BigInteger) {
generator.writeNumber((BigInteger) json);
} else if (json instanceof BigDecimal) {
generator.writeNumber((BigDecimal) json);
} else {
generator.writeNumber(((Number) json).doubleValue());
}
}
private static <T> T cast(Object o, Class<T> clazz) {
if (o instanceof Map) {
if (!clazz.isAssignableFrom(Map.class)) {
throw new DecodeException("Failed to decode");
}
if (clazz == Object.class) {
o = new JsonObject((Map) o);
}
return clazz.cast(o);
} else if (o instanceof List) {
if (!clazz.isAssignableFrom(List.class)) {
throw new DecodeException("Failed to decode");
}
if (clazz == Object.class) {
o = new JsonArray((List) o);
}
return clazz.cast(o);
} else if (o instanceof String) {
String str = (String) o;
if (clazz.isEnum()) {
o = Enum.valueOf((Class<Enum>) clazz, str);
} else if (clazz == byte[].class) {View on GitHub (pinned to fb308bd8c3)
Solutions
- Check that the JSON structure matches the expected type (object vs array vs scalar)
- Use fromJson with the correct target type or validate the payload shape first
Defensive patterns
Strategy: try-catch
When it happens
Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/json/jackson/JacksonCodec.java:512 when the library encounters an invalid state.
Common situations: See trigger scenarios.
Understand the failure class
- Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.
AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06).
Data as JSON: /api/errors/41b97b1ebd036ef8.
Report an issue: GitHub.