eclipse-vertx/vert.x · error · DecodeException

Invalid JSON array: ${json}

Error message

Invalid JSON array: ${json}

What it means

The JsonArray(String) constructor parses the string with Jackson; if parsing succeeds but the result is not a JSON array (e.g. it is an object, string, number, or invalid token), the internal list stays null and Vert.x throws DecodeException("Invalid JSON array: <json>").

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/JsonArray.java:61

public class JsonArray implements Iterable<Object>, ClusterSerializable, Shareable {

  private List<Object> list;

  /**
   * Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.
   * <p/>
   * If you are unsure of the value, you should use instead {@link Json#decodeValue(String)} and check the result is
   * a JSON array.
   *
   * @param json the string of JSON
   */
  public JsonArray(String json) {
    if (json == null) {
      throw new NullPointerException();
    }
    fromJson(json);
    if (list == null) {
      throw new DecodeException("Invalid JSON array: " + json);
    }
  }

  /**
   * Create an empty instance
   */
  public JsonArray() {
    list = new ArrayList<>();
  }

  /**
   * Create an instance from a List. The List is not copied.
   *
   * @param list the underlying backing list
   */
  public JsonArray(List list) {
    if (list == null) {
      throw new NullPointerException();

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the string: if it starts with '{', use new JsonObject(json) instead.
2. Trim whitespace/BOM and fix truncation before parsing.
3. Validate the payload is a JSON array first with the Jackson ObjectMapper readTree.
4. Wrap construction in try-catch on DecodeException for untrusted input.

Example fix

// before
JsonArray arr = new JsonArray(responseBody); // may be an object
// after
if (responseBody.trim().startsWith("[")) {
  JsonArray arr = new JsonArray(responseBody);
} else {
  JsonObject obj = new JsonObject(responseBody);
}

boolean isJsonArray(String s) { return s != null && s.trim().startsWith("["); }

JsonArray safeArray(String json) { return json != null && json.trim().startsWith("[") ? new JsonArray(json) : null; }

try { arr = new JsonArray(json); } catch (DecodeException e) { /* log json preview, handle non-array */ }

When it happens

Trigger: new JsonArray(string) where the string is empty, malformed, or contains a valid JSON value that is not an array (e.g. "{\"a\":1}" or "42").

Common situations: Passing a JSON object payload into JsonArray; truncated response body from an API; reading an empty file; string with BOM or whitespace-only content.

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: ${buf}
• Invalid JSON object: ${json}
• Invalid JSON object: ${buf}
• Failed to decode:${e.getMessage()}
• Unexpected trailing token

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