eclipse-vertx/vert.x · error · DecodeException

${ioe.getMessage()}

Error message

${ioe.getMessage()}

What it means

During parsing, Jackson may report IOExceptions (e.g. malformed JSON detected in non-blocking mode). JsonParserImpl collects them; if the user registered an exceptionHandler they are delivered there, otherwise the first exception is rethrown as a DecodeException wrapping the IOException message. It indicates the JSON stream being parsed is malformed or truncated.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/parsetools/impl/JsonParserImpl.java:336

          throw e;
        }
      } finally {
        emitting = false;
      }
    }
  }

  private void checkExceptions() {
    List<IOException> exceptions = collectedExceptions;
    collectedExceptions = null;
    if (exceptions != null && exceptions.size() > 0) {
      if (exceptionHandler != null) {
        for (IOException ioe : exceptions) {
          exceptionHandler.handle(ioe);
        }
      } else {
        IOException ioe = exceptions.get(0);
        throw new DecodeException(ioe.getMessage(), ioe);
      }
    }
  }

  @Override
  public JsonParser objectEventMode() {
    objectValueMode = false;
    return this;
  }

  @Override
  public JsonParser objectValueMode() {
    objectValueMode = true;
    return this;
  }

  @Override
  public JsonParser arrayEventMode() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Fix the source data to be valid JSON; validate payloads upstream
2. Register parser.exceptionHandler(ioe -> ...) to handle malformed data gracefully instead of an unhandled DecodeException
3. Inspect the DecodeException cause (IOException) and its message for the parser position of the malformed input

Example fix

// before
parser.handler(event -> handle(event));
stream.pipeTo(parser); // DecodeException on malformed input
// after
parser.exceptionHandler(ioe -> log.warn("Malformed JSON: {}", ioe.getMessage()));
parser.handler(event -> handle(event));
stream.pipeTo(parser);

parser.exceptionHandler(ioe -> {
  // handle malformed JSON without throwing
});
// and/or around consuming:
try {
  parser.end();
} catch (DecodeException e) {
  // e.getCause() is the underlying IOException with position details
}

When it happens

Trigger: Feeding invalid/truncated JSON to the parser without setting exceptionHandler(); parsing completes (end() or a buffer handler) and checkExceptions() fires the accumulated DecodeException.

Common situations: Upstream services sending malformed NDJSON; network truncation of a JSON body; parsing a stream that mixes JSON with non-JSON framing bytes.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• ${e.getMessage()}
• ${e}
• Parsing already done
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0

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