eclipse-vertx/vert.x · error · DecodeException

Invalid JSON object: ${json}

Error message

Invalid JSON object: ${json}

What it means

The JsonObject(String) constructor parses the string with Jackson; when the parsed value is not a JSON object (array, scalar, or malformed), the internal map stays null and DecodeException("Invalid JSON object: <json>") is thrown.

Source

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

 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
public class JsonObject implements Iterable<Map.Entry<String, Object>>, ClusterSerializable, Shareable {

  private Map<String, Object> map;

  /**
   * Create an instance from a string of JSON
   *
   * @param json the string of JSON
   */
  public JsonObject(String json) {
    if (json == null) {
      throw new NullPointerException();
    }
    fromJson(json);
    if (map == null) {
      throw new DecodeException("Invalid JSON object: " + json);
    }
  }

  /**
   * Create a new, empty instance
   */
  public JsonObject() {
    map = new LinkedHashMap<>();
  }

  /**
   * Create an instance from a Map. The Map is not copied.
   *
   * @param map the map to create the instance from.
   */
  public JsonObject(Map<String, Object> map) {
    if (map == null) {
      throw new NullPointerException();

View on GitHub (pinned to fb308bd8c3)

Solutions

1. If the string starts with '[', parse with new JsonArray(json) instead.
2. Trim the string and remove BOM/trailing whitespace before parsing.
3. Validate the JSON shape with Jackson readTree before constructing.
4. Catch DecodeException when parsing untrusted input and surface a clear config error.

Example fix

// before
JsonObject cfg = new JsonObject(configString); // may be [..]
// after
String s = configString.trim();
JsonObject cfg = s.startsWith("{") ? new JsonObject(s) : null;

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

JsonObject safeObject(String json) { return json != null && json.trim().startsWith("{") ? new JsonObject(json) : null; }

try { obj = new JsonObject(json); } catch (DecodeException e) { /* handle array/scalar/invalid payload */ }

When it happens

Trigger: new JsonObject(string) where the string is a JSON array ("[1,2]"), a scalar ("\"text\"", "42"), an empty string, or invalid JSON.

Common situations: Passing a JSON array where an object is expected; empty config file or env string; config service returning an array; trailing garbage after the 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: ${json}
• Invalid JSON array: ${buf}
• 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/de4719169a4540da. Report an issue: GitHub.