What causes "414 Request-URI Too Long" in eclipse-vertx/vert.x?

Move parameters into the request body: switch to POST with a JSON payload

414 Request-URI Too Long

Error message

414 Request-URI Too Long

What it means

SC_REQUEST_URI_TOO_LONG is the HttpResponseExpectation constant for HTTP 414 URI Too Long. Vert.x exposes it for response validation; a 414 failing this expectation reports '414 Request-URI Too Long'. The server refuses to process the request because the request target (method + URI + query string) exceeds its configured maximum length.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java:220

  /**
   * 411 Length Required
   */
  HttpResponseExpectation SC_LENGTH_REQUIRED = status(411);

  /**
   * 412 Precondition Failed
   */
  HttpResponseExpectation SC_PRECONDITION_FAILED = status(412);

  /**
   * 413 Request Entity Too Large
   */
  HttpResponseExpectation SC_REQUEST_ENTITY_TOO_LARGE = status(413);

  /**
   * 414 Request-URI Too Long
   */
  HttpResponseExpectation SC_REQUEST_URI_TOO_LONG = status(414);

  /**
   * 415 Unsupported Media Type
   */
  HttpResponseExpectation SC_UNSUPPORTED_MEDIA_TYPE = status(415);

  /**
   * 416 Requested Range Not Satisfiable
   */
  HttpResponseExpectation SC_REQUESTED_RANGE_NOT_SATISFIABLE = status(416);

  /**
   * 417 Expectation Failed
   */
  HttpResponseExpectation SC_EXPECTATION_FAILED = status(417);

  /**
   * 421 Misdirected Request

View on GitHub (pinned to fb308bd8c3)

Solutions

Move parameters into the request body: switch to POST with a JSON payload
Batch the parameters (chunk the ID list across multiple requests)
Compress/shorten identifiers (numeric IDs, cursor-based pagination instead of full filter lists)
Use server-side filters: upload a filter spec once, reference it by ID
Raise the URI limit on your own server/proxy only as a last resort

Example fix

// before
webClient.get(url + "?ids=" + String.join(",", thousandsOfIds)).send(); // 414
// after
webClient.post(url + "/search")
  .sendJsonObject(new JsonObject().put("ids", ids));

Defensive patterns

Strategy: validation

Validate before calling

// Check request line length before sending
String uri = path + "?" + queryParams;
if (uri.length() > MAX_URI_LENGTH /* e.g. 8000 */) {
  switchToPostBodyRequest(params);
}

Type guard

boolean isUriTooLong(Throwable t) {
  return t instanceof VertxHttpResponseException
    && ((VertxHttpResponseException) t).getResponse().statusCode() == 414;
}

Try / catch

if (isUriTooLong(t)) { convertToPostRequest(params); } else { throw t; }

Prevention

Cap query strings at a conservative length (e.g. 2000 chars)
Send large filter lists as a POST body
Use pagination/cursors instead of enumerating items in the URL
Never put large tokens or blobs in the URL

When it happens

Trigger: Building a GET request via Vert.x WebClient with a very long query string (huge filter lists, many IDs, large embedded tokens) so the request line exceeds the server/proxy URI size cap.

Common situations: Passing hundreds/thousands of comma-separated IDs as a query parameter, stuffing JWT or signed data into the URL, GET requests generated from large form state, proxies with stricter URI limits than the origin server.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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