{"record":{"id":"235856e8f8a3d6e3","repo":"eclipse-vertx/vert.x","slug":"failed-to-decode-235856","errorCode":null,"errorMessage":"Failed to decode","messagePattern":"Failed to decode","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/JacksonCodec.java","lineNumber":465,"sourceCode":"    } else if (json instanceof Float) {\n      generator.writeNumber((Float) json);\n    } else if (json instanceof Double) {\n      generator.writeNumber((Double) json);\n    } else if (json instanceof Byte) {\n      generator.writeNumber((Byte) json);\n    } else if (json instanceof BigInteger) {\n      generator.writeNumber((BigInteger) json);\n    } else if (json instanceof BigDecimal) {\n      generator.writeNumber((BigDecimal) json);\n    } else {\n      generator.writeNumber(((Number) json).doubleValue());\n    }\n  }\n\n  private static <T> T cast(Object o, Class<T> clazz) {\n    if (o instanceof Map) {\n      if (!clazz.isAssignableFrom(Map.class)) {\n        throw new DecodeException(\"Failed to decode\");\n      }\n      if (clazz == Object.class) {\n        o = new JsonObject((Map) o);\n      }\n      return clazz.cast(o);\n    } else if (o instanceof List) {\n      if (!clazz.isAssignableFrom(List.class)) {\n        throw new DecodeException(\"Failed to decode\");\n      }\n      if (clazz == Object.class) {\n        o = new JsonArray((List) o);\n      }\n      return clazz.cast(o);\n    } else if (o instanceof String) {\n      String str = (String) o;\n      if (clazz.isEnum()) {\n        o = Enum.valueOf((Class<Enum>) clazz, str);\n      } else if (clazz == byte[].class) {","sourceCodeStart":447,"sourceCodeEnd":483,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/JacksonCodec.java#L447-L483","documentation":"JacksonCodec.cast narrows a decoded value to the requested class. When the decoded value is a Map but the target class cannot accept a Map (clazz.isAssignableFrom(Map.class) is false), it throws DecodeException(\"Failed to decode\"). This means the JSON document was an object but you asked to decode it into an incompatible type (e.g. a List or String class).","triggerScenarios":"Calling JacksonCodec.cast(mapValue, SomeClass) or decoding JSON with Json.decodeValue(buffer, X.class) where the JSON is an object and X is not Map, Object, JsonObject, or any supertype of Map — e.g. decodeValue(json, List.class) on '{\"a\":1}'.","commonSituations":"Decoding an API response that changed from an array to an object while the target type stayed List; asking for a POJO class without databind on the classpath so the raw Map cannot be mapped onto it; passing Integer.class/String.class for object-shaped JSON.","solutions":["Match the target type to the JSON shape: use Map.class/JsonObject.class for objects, List.class/JsonArray.class for arrays","Decode without a target class (Json.decodeValue(buffer)) and convert manually, or use a POJO mapping with jackson-databind available","If the payload changed shape, update the producer or adapt the consumer's expected type"],"exampleFix":"// before\nMap<String,Object> m = Json.decodeValue(\"{\\\"a\\\":1}\", List.class); // DecodeException: Failed to decode\n// after\nMap<String,Object> m = Json.decodeValue(\"{\\\"a\\\":1}\", Map.class);\n// or: JsonObject o = Json.decodeValue(\"{\\\"a\\\":1}\", JsonObject.class);","handlingStrategy":"type-guard","validationCode":"String t = input.trim();\nif (!t.startsWith(\"{\")) throw new IllegalArgumentException(\"payload is not a JSON object\");","typeGuard":"static <T> boolean decodableAsMap(Class<T> c) {\n  return c == Object.class || c.isAssignableFrom(Map.class);\n}","tryCatchPattern":"try {\n  T v = Json.decodeValue(buffer, targetType);\n} catch (DecodeException e) {\n  if (\"Failed to decode\".equals(e.getMessage())) {\n    // JSON shape does not match target type; decode without target and inspect\n    Object raw = Json.decodeValue(buffer);\n  }\n}","preventionTips":["Match decode target to payload shape: Map/JsonObject for objects","Avoid decoding object payloads into POJO classes when jackson-databind is absent","Pin API response shapes with contract tests to catch producer drift"],"tags":["java","json","decoding","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}