eclipse-vertx/vert.x · error · DecodeException

Failed to decode: ${e.getMessage()}

Error message

Failed to decode: ${e.getMessage()}

What it means

The private adapt() method converts Jackson-produced List/Map values into Vert.x JsonArray/JsonObject after decoding; any exception during that adaptation is wrapped in DecodeException. It is invoked from fromValue and fromParser, so a decode that cannot be mapped to Vert.x JSON types surfaces here.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/jackson/DatabindCodec.java:235

        .writeValue(writer, object);
    } catch (Exception e) {
      throw new EncodeException("Failed to encode as JSON: " + e.getMessage());
    }
  }

  private static Object adapt(Object o) {
    try {
      if (o instanceof List) {
        List list = (List) o;
        return new JsonArray(list);
      } else if (o instanceof Map) {
        @SuppressWarnings("unchecked")
        Map<String, Object> map = (Map<String, Object>) o;
        return new JsonObject(map);
      }
      return o;
    } catch (Exception e) {
      throw new DecodeException("Failed to decode: " + e.getMessage());
    }
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the cause message to find which value could not be adapted
2. Sanitize decoded maps (no null keys) before they reach JsonObject construction
3. Decode to a plain type (Map/List) with Jackson directly if Vert.x JSON wrappers are not required
4. Catch DecodeException around fromParser/fromValue for untrusted inputs

Example fix

// before
Object o = DatabindCodec.fromParser(parser, null); // DecodeException from adapt
// after
try {
  Object o = DatabindCodec.fromParser(parser, null);
} catch (DecodeException e) {
  log.warn("unadaptable json payload", e);
}

try {
  Object o = Json.decodeValue(json);
} catch (DecodeException e) {
  // also covers adapt() failures
}

if (decoded instanceof JsonObject || decoded instanceof JsonArray || decoded instanceof Map || decoded instanceof List) { /* adaptable shapes */ }

try {
  Object o = DatabindCodec.fromParser(parser, null);
} catch (DecodeException e) {
  log.warn("payload could not be adapted to Vert.x JSON: {}", e.getMessage());
}

When it happens

Trigger: Decoding JSON whose resulting Map keys or values cannot be adapted, or a Map constructor of JsonObject throwing (e.g. null key in the map); also any exception thrown inside adapt's List/Map conversion.

Common situations: Decoding JSON with duplicate or unusual keys; custom deserializers producing maps with null keys; using fromParser pipelines where intermediate values are not plain List/Map types.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid JSON array: ${json}
• Invalid JSON array: ${buf}
• Invalid JSON object: ${json}
• Invalid JSON object: ${buf}
• Expected a base64 encoded byte array

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/3029b4578edd8dbf. Report an issue: GitHub.