eclipse-vertx/vert.x · error · VertxException

Invalid url:

Error message

Invalid url: 

What it means

RequestOptions.parseUrl wraps java.net.URL construction failures. When an absolute URL string set via setAbsoluteURL (or routed through the url(String) option) cannot be parsed as a well-formed URL, Vert.x throws this VertxException wrapping the underlying MalformedURLException. It means the URL string itself is malformed — missing protocol, illegal characters, or unsupported scheme.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/RequestOptions.java:313

   * e.g. {@code Future<HttpClientResponse>} or {@code Future<Buffer>} response body.
   *
   * <p/>The timeout starts after a connection is obtained from the client, similar to calling
   * {@link HttpClientRequest#idleTimeout(long)}.
   *
   * @param timeout the amount of time in milliseconds.
   * @return a reference to this, so the API can be used fluently
   */
  public RequestOptions setIdleTimeout(long timeout) {
    this.idleTimeout = timeout;
    return this;
  }

  private URL parseUrl(String surl) {
    // Note - parsing a URL this way is slower than specifying host, port and relativeURI
    try {
      return new URL(surl);
    } catch (MalformedURLException e) {
      throw new VertxException("Invalid url: " + surl, e);
    }
  }

  /**
   * Parse an absolute URI to use, this will update the {@code ssl}, {@code host},
   * {@code port} and {@code uri} fields.
   *
   * @param absoluteURI the uri to use
   * @return a reference to this, so the API can be used fluently
   */
  public RequestOptions setAbsoluteURI(String absoluteURI) {
    Objects.requireNonNull(absoluteURI, "Cannot set a null absolute URI");
    URL url = parseUrl(absoluteURI);
    return setAbsoluteURI(url);
  }

  /**
   * Like {@link #setAbsoluteURI(String)} but using an {@link URL} parameter.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure the URL string includes a valid scheme and host, e.g. 'http://host:port/path'.
2. Pre-validate with new java.net.URL(s) in a try/catch or use URI.create before passing to setAbsoluteURL.
3. Encode illegal characters with URLEncoder/URI multi-argument constructor instead of raw string interpolation.
4. Alternatively specify host, port, and URI separately via setHost/setPort/setURI to avoid full-URL parsing.

Example fix

// before
RequestOptions opts = new RequestOptions().setAbsoluteURL(baseHost + ":8080/api");
// after
RequestOptions opts = new RequestOptions().setAbsoluteURL("http://" + baseHost + ":8080/api");

static boolean isValidUrl(String s) {
  try { new java.net.URL(s); return true; } catch (MalformedURLException e) { return false; }
}
// use: if (!isValidUrl(url)) throw new IllegalArgumentException("bad url: " + url);

When it happens

Trigger: Calling RequestOptions.setAbsoluteURL(String) with a string like "localhost:8080/path" (no scheme), "http://" (empty host), or a URL containing spaces or other illegal characters; the resulting options are then used to build an HttpClientRequest.

Common situations: Building the URL by string concatenation and forgetting the 'http://' prefix; user-supplied URLs passed through unvalidated; environment-specific config where the scheme was dropped; copying a URI containing non-ASCII characters without encoding.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• Scheme:
• Client is closed
• HTTP client must be configured for at least one HTTP version
• Only socket address are currently supported
• no null chunk accepted

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