eclipse-vertx/vert.x · error · DecodeException

Invalid JSON array: ${buf}

Error message

Invalid JSON array: ${buf}

What it means

The JsonArray(Buffer) constructor decodes the buffer as JSON; if decoding does not produce an array (object, scalar, empty or malformed bytes), the internal list stays null and DecodeException("Invalid JSON array: <buf>") is thrown.

Source

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

  public JsonArray(List list) {
    if (list == null) {
      throw new NullPointerException();
    }
    this.list = list;
  }

  /**
   * Create an instance from a Buffer of JSON.
   *
   * @param buf the buffer of JSON.
   */
  public JsonArray(Buffer buf) {
    if (buf == null) {
      throw new NullPointerException();
    }
    fromBuffer(buf);
    if (list == null) {
      throw new DecodeException("Invalid JSON array: " + buf);
    }
  }

  /**
   * Create a JsonArray containing an arbitrary number of values.
   *
   * @param values The objects into JsonArray.
   * @throws NullPointerException if the args is null.
   */
  public static JsonArray of(Object... values) {
    // implicit nullcheck of values
    if (values.length == 0) {
      return new JsonArray();
    }

    JsonArray arr = new JsonArray(new ArrayList<>(values.length));
    for(int i = 0; i< values.length; ++i) {
      arr.add(values[i]);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check the buffer content: if it decodes to an object use JsonObject(Buffer) instead.
2. Guard against empty buffers before parsing.
3. Log/print the buffer (toString) to see the actual payload and fix the producer or the expected type.
4. Catch DecodeException and fall back to alternate parsing for untrusted sources.

Example fix

// before
JsonArray arr = new JsonArray(body); // body might be {}
// after
if (body.length() > 0 && body.toString().trim().startsWith("[")) {
  JsonArray arr = new JsonArray(body);
}

boolean isJsonArrayBuffer(Buffer b) { return b != null && b.length() > 0 && b.toString().trim().startsWith("["); }

JsonArray safeArray(Buffer buf) { return buf != null && buf.length() > 0 && buf.toString().trim().startsWith("[") ? new JsonArray(buf) : null; }

try { arr = new JsonArray(buf); } catch (DecodeException e) { /* inspect buf.toString(), handle non-array payload */ }

When it happens

Trigger: new JsonArray(buffer) where the Buffer holds a JSON object, an empty payload, or corrupt/truncated bytes — e.g. an HTTP response body that is not an array.

Common situations: Consuming an HTTP endpoint that returns {"error":...} while the client expects a JSON array; empty 200 responses; binary/corrupt payloads from a queue or file.

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 object: ${buf}
• Invalid JSON object: ${json}
• Expected a base64 encoded byte array
• Failed to decode:${e.getMessage()}

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