{"record":{"id":"2c46ea313de35131","repo":"eclipse-vertx/vert.x","slug":"expecting-the-current-parser-token-to-be-the-start-2c46ea","errorCode":null,"errorMessage":"Expecting the current parser token to be the start of an array","messagePattern":"Expecting the current parser token to be the start of an array","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/JacksonCodec.java","lineNumber":323,"sourceCode":"    obj.put(key2, value2);\n    do {\n      parser.nextToken();\n      Object value = parseValue(parser);\n      obj.put(key, value);\n      key = parser.nextName();\n    } while (key != null);\n    return obj;\n  }\n\n  /**\n   * Parse a JSON array given the {@code parser}, the parser current token must be {@link JsonTokenId#ID_START_ARRAY}\n   *\n   * @param parser the parser\n   * @return the parsed array\n   */\n  public static List<Object> parseArray(JsonParser parser) throws IOException {\n    if (parser.currentTokenId() != JsonTokenId.ID_START_ARRAY) {\n      throw new DecodeException(\"Expecting the current parser token to be the start of an array\");\n    }\n    return internalParseArray(parser);\n  }\n\n  private static List<Object> internalParseArray(JsonParser parser) throws IOException {\n    List<Object> array = new ArrayList<>();\n    while (true) {\n      parser.nextToken();\n      int tokenId = parser.currentTokenId();\n      if (tokenId == JsonTokenId.ID_PROPERTY_NAME) {\n        throw new UnsupportedOperationException();\n      } else if (tokenId == JsonTokenId.ID_END_ARRAY) {\n        return array;\n      }\n      Object value = parseValue(parser);\n      array.add(value);\n    }\n  }","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/JacksonCodec.java#L305-L341","documentation":"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.","triggerScenarios":"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()).","commonSituations":"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.","solutions":["Advance the parser so currentToken is START_ARRAY before calling parseArray (parser.nextToken())","If the payload may be an object, dispatch on the first token: parseObject for START_OBJECT, parseArray for START_ARRAY","Unwrap enveloped responses ({\"items\":...}) and pass the inner array parser/token instead"],"exampleFix":"// before\nJsonParser p = mapper.createParser(\"{\\\"items\\\":[1]}\");\np.nextToken();\nList<Object> l = JacksonCodec.parseArray(p); // DecodeException\n// after\nJsonParser p = mapper.createParser(\"{\\\"items\\\":[1]}\");\np.nextToken(); // START_OBJECT\np.nextToken(); // \"items\"\np.nextToken(); // START_ARRAY\nList<Object> l = JacksonCodec.parseArray(p);","handlingStrategy":"type-guard","validationCode":"String t = input.trim();\nif (!t.startsWith(\"[\")) throw new IllegalArgumentException(\"expected a JSON array\");","typeGuard":"static boolean isJsonArrayToken(JsonParser p) {\n  return p.currentTokenId() == JsonTokenId.ID_START_ARRAY;\n}","tryCatchPattern":"try {\n  List<Object> l = JacksonCodec.parseArray(parser);\n} catch (DecodeException e) {\n  // parser not positioned on START_ARRAY — inspect token and dispatch\n}","preventionTips":["Advance the parser (nextToken()) before calling parseArray","Unwrap enveloped responses (objects containing the array) before list-decoding","Check the first character of the payload to pick parseObject vs parseArray"],"tags":["java","json","decoding","parser-state"],"backgroundTag":"json-parse-error","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}