eclipse-vertx/vert.x · error · IllegalArgumentException

invalid escape sequence `%${c}${c2}' at index ${i - 2} of: $

Error message

invalid escape sequence `%${c}${c2}' at index ${i - 2} of: ${s}

What it means

URI decoding failure in decodeAndTransformURIComponent: the two characters following '%' are not valid hexadecimal digits, so decodeHexNibble returned an invalid marker. The message reports the bad sequence and its index within the string; the input at fault is the malformed percent-escape in the URI component.

Source

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

      char c = s.charAt(i);
      if (c == '%') {
        if (i == size - 1) {
          throw new IllegalArgumentException("unterminated escape"
            + " sequence at end of string: " + s);
        }
        c = s.charAt(++i);
        if (c == '%') {
          buf[pos++] = '%';  // "%%" -> "%"
          break;
        }
        if (i >= size - 1) {
          throw new IllegalArgumentException("partial escape"
            + " sequence at end of string: " + s);
        }
        c = decodeHexNibble(c);
        final char c2 = decodeHexNibble(s.charAt(++i));
        if (c == Character.MAX_VALUE || c2 == Character.MAX_VALUE) {
          throw new IllegalArgumentException(
            "invalid escape sequence `%" + s.charAt(i - 1)
              + s.charAt(i) + "' at index " + (i - 2)
              + " of: " + s);
        }
        c = (char) (c * 16 + c2);
        // shouldn't check for plus since it would be a double decoding
        buf[pos++] = (byte) c;
      } else {
        buf[pos++] = (byte) (plus && c == '+' ? ' ' : c);
      }
    }
    return new String(buf, 0, pos, StandardCharsets.UTF_8);
  }

  /**
   * Helper to decode half of a hexadecimal number from a string.
   * @param c The ASCII character of the hexadecimal number to decode.
   * Must be in the range {@code [0-9a-fA-F]}.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Correct the escape to valid hex (e.g. '%2F') or encode the literal character properly
2. Sanitize URIs from untrusted input before decoding

When it happens

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