eclipse-vertx/vert.x · error

421 Misdirected Request

Error message

421 Misdirected Request

What it means

SC_MISDIRECTED_REQUEST is a Vert.x HttpResponseExpectation constant representing HTTP status 421. It is used with the HttpClient 'expecting(...)' API to assert that a response has status 421, or to fail a request chain when the server reports the response was sent to a server unable to produce a response for the combination of scheme/authority in the request URI. HTTP/2 servers (e.g. when connection coalescing is misconfigured) commonly emit 421.

Source

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

  /**
   * 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
   */
  HttpResponseExpectation SC_MISDIRECTED_REQUEST = status(421);

  /**
   * 422 Unprocessable Entity (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_UNPROCESSABLE_ENTITY = status(422);

  /**
   * 423 Locked (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_LOCKED = status(423);

  /**
   * 424 Failed Dependency (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_FAILED_DEPENDENCY = status(424);

  /**
   * 425 Unordered Collection (WebDAV, RFC3648)

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Verify the request URI authority (host:port) matches a virtual host the target server actually serves, and that SNI/TLS certificates cover it.
2. Disable connection sharing/coalescing (e.g. per-host HttpClients or set the correct authority) so requests are not reused across mismatched origins.
3. Fix reverse proxy / load balancer routing rules so the Host header is forwarded and routed to the correct backend.
4. If you intentionally test for 421, keep the expectation; otherwise switch to a success expectation (SC_OK or SC_SUCCESSFUL).

Example fix

// before
client.request(new RequestOptions().setHost("wrong.example.com"))
  .compose(HttpClientRequest::send)
  .expecting(HttpResponseExpectation.SC_OK)...
// after
client.request(new RequestOptions().setHost("correct.example.com").setPort(443).setSsl(true))
  .compose(HttpClientRequest::send)
  .expecting(HttpResponseExpectation.SC_OK)...

if (!expectedHosts.contains(requestOptions.getHost())) {
  throw new IllegalStateException("host " + requestOptions.getHost() + " not served by this connection");
}

boolean is421(HttpClientResponse resp) { return resp.statusCode() == 421; }

// expectation failure surfaces as VertxException/HttpException in the future
request.compose(HttpClientRequest::send)
  .expecting(HttpResponseExpectation.SC_OK)
  .onFailure(err -> { if (isCauseStatus(err, 421)) rerouteToCorrectAuthority(); });

When it happens

Trigger: A request is sent to a host/port combination the server is not the authoritative server for, typically over HTTP/2 after connection reuse/coalescing, or when SNI/hostname does not match the virtual host the client targeted. Used as a validation expectation: client.request(...).expecting(HttpResponseExpectation.SC_MISDIRECTED_REQUEST).

Common situations: HTTP/2 connection coalescing across origins with mismatched TLS certificates; reverse proxy or load balancer routing a request to the wrong backend vhost; SNI misconfiguration after a domain move; CDN pointing at a server that does not serve that Host header.

Related errors

• http2MaxPoolSize must be > 0
• Cannot write an HTTP/2 frame over an HTTP/1.x connection
• HTTP/1.x connections don't support SETTINGS
• HTTP/1.x connections don't support PING
• Please set handler before server is listening

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