eclipse-vertx/vert.x · error · DecodeException

Invalid JSON object: ${buf}

Error message

Invalid JSON object: ${buf}

What it means

JsonObject(Buffer) throws DecodeException when the buffer's bytes cannot be decoded into a JSON object (e.g. they contain a JSON array, string, or invalid data). The null-buffer case is a separate NullPointerException. Vert.x requires the buffer to hold a valid JSON object value.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/JsonObject.java:88

  public JsonObject(Map<String, Object> map) {
    if (map == null) {
      throw new NullPointerException();
    }
    this.map = map;
  }

  /**
   * Create an instance from a buffer.
   *
   * @param buf the buffer to create the instance from.
   */
  public JsonObject(Buffer buf) {
    if (buf == null) {
      throw new NullPointerException();
    }
    fromBuffer(buf);
    if (map == null) {
      throw new DecodeException("Invalid JSON object: " + buf);
    }
  }

  /**
   * Create a JsonObject containing zero mappings.
   *
   * @return an empty JsonObject.
   */
  public static JsonObject of() {
    return new JsonObject();
  }

  /**
   * Create a JsonObject containing a single mapping.
   *
   * @param k1 the mapping's key
   * @param v1 the mapping's value
   * @return a JsonObject containing the specified mapping.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect/print the buffer content (buf.toString()) to see what is actually being parsed.
2. If the payload is a JSON array, parse it as JsonArray: new JsonArray(buf).
3. Validate the bytes are well-formed JSON object text before constructing (e.g. Json.decodeValue first).
4. Fix the upstream producer or config source to emit a single JSON object.

Example fix

// before
JsonObject obj = new JsonObject(buffer); // DecodeException if buffer holds an array
// after
Object decoded = Json.decodeValue(buffer);
JsonObject obj = decoded instanceof JsonObject
  ? (JsonObject) decoded
  : new JsonObject().put("items", decoded);

Object decoded = Json.decodeValue(buf); // throws early with a clearer message
if (!(decoded instanceof JsonObject)) throw new IllegalArgumentException("Expected JSON object, got " + decoded.getClass().getSimpleName());

boolean isJsonObject(Buffer buf) {
  try { return Json.decodeValue(buf) instanceof JsonObject; } catch (DecodeException e) { return false; }
}

try {
  JsonObject obj = new JsonObject(buf);
} catch (DecodeException e) {
  logger.error("Not a JSON object: {}", buf, e);
  // fall back to defaults or JsonArray handling
}

When it happens

Trigger: new JsonObject(Buffer) called with a buffer containing: an empty/blank payload, a JSON array like '[1,2]', a bare scalar like '"text"' or '42', trailing garbage, or truncated/invalid JSON.

Common situations: Reading a config file that is actually a JSON array or is empty; consuming an HTTP response body that is a JSON array instead of an object; a producer wrote newline-delimited JSON and a consumer tries to parse the whole stream as one object.

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 array: ${json}
• 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/de59914606434937. Report an issue: GitHub.