eclipse-vertx/vert.x · error · IllegalArgumentException

The provided pointer is not a valid JSON Pointer

Error message

The provided pointer is not a valid JSON Pointer

What it means

Parsing failure in JsonPointerImpl.parse: the pointer string does not match the RFC 6901 JSON Pointer grammar (valid pattern: optional URI fragment, then '/'-prefixed tokens with ~0/~1 escapes). The exception is thrown during JsonPointer construction; the input at fault is the pointer string.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/pointer/impl/JsonPointerImpl.java:71

  }

  public JsonPointerImpl(URI startingUri, List<String> decodedTokens) {
    this.startingUri = startingUri;
    this.decodedTokens = new ArrayList<>(decodedTokens);
  }

  private ArrayList<String> parse(String pointer) {
    if (pointer == null || "".equals(pointer)) {
      return new ArrayList<>();
    }
    if (VALID_POINTER_PATTERN.matcher(pointer).matches()) {
      return Arrays
          .stream(pointer.split("\\/", -1))
          .skip(1) //Ignore first element
          .map(this::unescape)
          .collect(Collectors.toCollection(ArrayList::new));
    } else
      throw new IllegalArgumentException("The provided pointer is not a valid JSON Pointer");
  }

  private String escape(String path) {
    return path.replace("~", "~0")
        .replace("/", "~1");
  }

  private String unescape(String path) {
    return path.replace("~1", "/") // https://tools.ietf.org/html/rfc6901#section-4
        .replace("~0", "~");
  }

  @Override
  public boolean isRootPointer() {
    return decodedTokens.size() == 0;
  }

  @Override

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a valid pointer like '/a/b' or the empty pointer
2. Escape '~' as '~0' and '/' as '~1' inside tokens
3. Validate pointer strings from untrusted input before constructing JsonPointer

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/json/pointer/impl/JsonPointerImpl.java:71 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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