eclipse-vertx/vert.x · error · DecodeException

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

Error message

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

What it means

Vert.x's JacksonCodec wraps any IOException raised while creating or driving a Jackson JsonParser over an InputStream into a DecodeException with this message. It signals that the JSON input stream could not be parsed (malformed JSON, I/O failure, or encoding problem). The cause retains the original Jackson exception.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/jackson/JacksonCodec.java:141

  @Override
  public <T> T fromString(String json, Class<T> clazz) throws DecodeException {
    return fromParser(createParser(json), clazz);
  }

  @Override
  public <T> T fromBuffer(Buffer json, Class<T> clazz) throws DecodeException {
    return fromParser(createParser(json), clazz);
  }

  @Override
  public <T> T fromStream(InputStream in, Class<T> clazz) throws DecodeException {
    try {
      JsonParser parser = factory.createParser(in);
      parser.disable(JsonParser.Feature.AUTO_CLOSE_SOURCE);
      return fromParser(parser, clazz);
    } catch (IOException e) {
      throw new DecodeException("Failed to decode:" + e.getMessage(), e);
    }
  }

  @Override
  public <T> T fromValue(Object json, Class<T> toValueType) {
    throw new DecodeException("Mapping " + toValueType.getName() + "  is not available without Jackson Databind on the classpath");
  }

  @Override
  public String toString(Object object, boolean pretty) throws EncodeException {
    BufferRecycler br = factory._getBufferRecycler();
    try (SegmentedStringWriter sw = new SegmentedStringWriter(br)) {
      JsonGenerator generator = createGenerator(sw, pretty);
      encodeJson(object, generator);
      generator.close();
      return sw.getAndClear();
    } catch (IOException e) {
      throw new EncodeException(e.getMessage(), e);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Validate the JSON payload with a parser or linter before decoding
2. Inspect the cause (DecodeException.getCause()) for the exact Jackson parse error and offset
3. Ensure the InputStream is fully available and uses a UTF-compatible encoding
4. If wrapping a socket/file stream, check the source is complete and not closed early

Example fix

// before
MyConfig cfg = JacksonCodec.fromStream(in, MyConfig.class); // throws on bad JSON
// after
try {
  MyConfig cfg = JacksonCodec.fromStream(in, MyConfig.class);
} catch (DecodeException e) {
  logger.error("Invalid JSON input: " + e.getCause().getMessage());
}

// Java
public static boolean isPlausibleJson(InputStream in) {
  try {
    in.mark(1);
    int c = in.read();
    in.reset();
    return c == '{' || c == '[' || c == '"' || c == '-' || Character.isDigit(c);
  } catch (IOException e) { return false; }
}

public static boolean isJsonStart(String s) {
  if (s == null) return false;
  String t = s.stripLeading();
  return !t.isEmpty() && "[{\"tfn-0".indexOf(t.charAt(0)) >= 0 || (!t.isEmpty() && Character.isDigit(t.charAt(0)));
}

try {
  T value = JacksonCodec.fromStream(in, T.class);
} catch (DecodeException e) {
  // e.getCause() is the Jackson IOException with parse details
  logger.error("JSON decode failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
  throw new BadRequestException("Malformed JSON payload");
}

When it happens

Trigger: Calling JacksonCodec.fromStream(InputStream, Class) (or DatabindCodec's equivalent path) where the stream contains malformed JSON, is closed mid-read, has an invalid encoding, or the underlying InputStream throws an IOException during read.

Common situations: Decoding a JSON file or network stream with truncated content; decoding data with a BOM or wrong charset; passing a stream whose source (socket/file) died during read; deserializing into a target class Jackson cannot map when Databind is present but the JSON is invalid.

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

• Failed to decode:
• Expecting the current parser token to be the start of an obj
• Expecting the current parser token to be the start of an arr
• Failed to decode:
• workerPoolSize must be > 0

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