eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid escape sequence: %${escapeSequence}

Error message

Invalid escape sequence: %${escapeSequence}

What it means

URI path decoding failure in decodeUnreserved: a percent escape in the path either has non-hex digits or the decoded value is not an unreserved character (it is a reserved/invalid codepoint that must stay escaped per RFC 3986). The offending escape sequence is reported in the message.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/internal/net/RFC3986.java:296

      // http://tools.ietf.org/html/rfc3986#section-2.4
      if (path.charAt(start) == '%') {
        decodeUnreserved(path, start);
      }

      start++;
    }
  }

  private static void decodeUnreserved(StringBuilder path, int start) {
    if (start + 3 <= path.length()) {
      // these are latin chars so there is no danger of falling into some special unicode char that requires more
      // than 1 byte
      final String escapeSequence = path.substring(start + 1, start + 3);
      int unescaped;
      try {
        unescaped = Integer.parseInt(escapeSequence, 16);
        if (unescaped < 0) {
          throw new IllegalArgumentException("Invalid escape sequence: %" + escapeSequence);
        }
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Invalid escape sequence: %" + escapeSequence);
      }
      // validate if the octet is within the allowed ranges
      if (
        // ALPHA
        (unescaped >= 0x41 && unescaped <= 0x5A) ||
          (unescaped >= 0x61 && unescaped <= 0x7A) ||
          // DIGIT
          (unescaped >= 0x30 && unescaped <= 0x39) ||
          // HYPHEN
          (unescaped == 0x2D) ||
          // PERIOD
          (unescaped == 0x2E) ||
          // UNDERSCORE
          (unescaped == 0x5F) ||
          // TILDE

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Keep reserved characters percent-encoded in paths
2. Fix malformed hex sequences in the source path

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/internal/net/RFC3986.java:296 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/4ed7f75512daffb2. Report an issue: GitHub.