eclipse-vertx/vert.x · error · DecodeException

Expecting the current parser token to be the start of an arr

Error message

Expecting the current parser token to be the start of an array

What it means

JacksonCodec.parseArray requires the JsonParser's current token to be START_ARRAY; otherwise it throws DecodeException. Like parseObject, it assumes the caller has positioned the parser at the array's opening token. Any other current token (object, scalar, or unset) is rejected.

Source

Thrown at vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/JacksonCodec.java:323

    obj.put(key2, value2);
    do {
      parser.nextToken();
      Object value = parseValue(parser);
      obj.put(key, value);
      key = parser.nextName();
    } while (key != null);
    return obj;
  }

  /**
   * Parse a JSON array given the {@code parser}, the parser current token must be {@link JsonTokenId#ID_START_ARRAY}
   *
   * @param parser the parser
   * @return the parsed array
   */
  public static List<Object> parseArray(JsonParser parser) throws IOException {
    if (parser.currentTokenId() != JsonTokenId.ID_START_ARRAY) {
      throw new DecodeException("Expecting the current parser token to be the start of an array");
    }
    return internalParseArray(parser);
  }

  private static List<Object> internalParseArray(JsonParser parser) throws IOException {
    List<Object> array = new ArrayList<>();
    while (true) {
      parser.nextToken();
      int tokenId = parser.currentTokenId();
      if (tokenId == JsonTokenId.ID_PROPERTY_NAME) {
        throw new UnsupportedOperationException();
      } else if (tokenId == JsonTokenId.ID_END_ARRAY) {
        return array;
      }
      Object value = parseValue(parser);
      array.add(value);
    }
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Advance the parser so currentToken is START_ARRAY before calling parseArray (parser.nextToken())
2. If the payload may be an object, dispatch on the first token: parseObject for START_OBJECT, parseArray for START_ARRAY
3. Unwrap enveloped responses ({"items":...}) and pass the inner array parser/token instead

Example fix

// before
JsonParser p = mapper.createParser("{\"items\":[1]}");
p.nextToken();
List<Object> l = JacksonCodec.parseArray(p); // DecodeException
// after
JsonParser p = mapper.createParser("{\"items\":[1]}");
p.nextToken(); // START_OBJECT
p.nextToken(); // "items"
p.nextToken(); // START_ARRAY
List<Object> l = JacksonCodec.parseArray(p);

String t = input.trim();
if (!t.startsWith("[")) throw new IllegalArgumentException("expected a JSON array");

static boolean isJsonArrayToken(JsonParser p) {
  return p.currentTokenId() == JsonTokenId.ID_START_ARRAY;
}

try {
  List<Object> l = JacksonCodec.parseArray(parser);
} catch (DecodeException e) {
  // parser not positioned on START_ARRAY — inspect token and dispatch
}

When it happens

Trigger: Calling JacksonCodec.parseArray(parser) when the input is a JSON object ('{...}'), a scalar, or when the parser has not been advanced to the first token (currentTokenId() != ID_START_ARRAY, e.g. right after createParser without nextToken()).

Common situations: API changed its response from a JSON array to an enveloped object like {"items":[...]}; forgetting parser.nextToken() when driving the parser manually; passing a single-element payload where a list was expected.

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

• Expecting the current parser token to be the start of an obj
• Unexpected trailing token
• Failed to decode
• Failed to decode:${e.getMessage()}
• Mapping ${toValueType.getName()} is not available without J

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