eclipse-vertx/vert.x · error · DecodeException

${e.getMessage()}

Error message

${e.getMessage()}

What it means

JsonEvent.mapTo converts the event's parsed JSON value into the given Java class using the Jackson databind codec. If Jackson cannot map the value (missing properties, wrong shape, type mismatch), the exception is rethrown as a DecodeException whose message is the underlying failure's message. It signals that the JSON does not conform to the target type.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/parsetools/impl/JsonEventImpl.java:99

    return type == JsonEventType.VALUE && value == null;
  }

  @Override
  public boolean isObject() {
    return value instanceof JsonObject;
  }

  @Override
  public boolean isArray() {
    return value instanceof JsonArray;
  }

  @Override
  public <T> T mapTo(Class<T> type) {
    try {
      return JacksonFactory.CODEC.fromValue(value, type);
    } catch (Exception e) {
      throw new DecodeException(e.getMessage(), e);
    }
  }

  @Override
  public Integer integerValue() {
    if (value != null) {
      Number number = (Number) value;
      if (value instanceof Integer) {
        return (Integer)value;  // Avoids unnecessary unbox/box
      } else {
        return number.intValue();
      }
    }
    return null;
  }

  @Override
  public Long longValue() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the DecodeException message to find the Jackson failure and fix the JSON or target class
2. Annotate the target class with @JsonIgnoreProperties(ignoreUnknown = true) or configure the ObjectMapper to be lenient
3. Validate the event shape (e.g. check isObject/fieldNames) before calling mapTo

Example fix

// before
User u = event.mapTo(User.class); // DecodeException on shape mismatch
// after
if (event.type() == JsonEventType.OBJECT) {
  try {
    User u = event.mapTo(User.class);
  } catch (DecodeException e) {
    log.warn("Bad payload: {}", e.getMessage());
  }
}

if (event.type() != JsonEventType.OBJECT || !event.fieldNames().containsAll(requiredFields)) {
  throw new DecodeException("Event does not match expected shape");
}

boolean isObjectEvent(JsonEvent e) {
  return e.type() == JsonEventType.OBJECT;
}

try {
  User u = event.mapTo(User.class);
} catch (DecodeException e) {
  // log e.getMessage(); reject or skip the event
}

When it happens

Trigger: Mapping a JSON object to a POJO whose required properties are missing or of incompatible types; mapping a non-object value to a class; unknown properties when the mapper is configured to fail on them.

Common situations: Deserializing JSON event streams into DTOs during JSON-RPC or NDJSON processing; schema drift between producer and consumer; numbers-as-strings vs numbers type mismatches.

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

• Failed to decode: ${e.getMessage()}
• ${ioe.getMessage()}
• ${e.getMessage()}
• Mapping
• workerPoolSize must be > 0

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