eclipse-vertx/vert.x · critical

500 Internal Server Error

Error message

500 Internal Server Error

What it means

SC_INTERNAL_SERVER_ERROR is an HttpResponseExpectation constant for HTTP 500. Vert.x applications use it with HttpClient 'expecting(...)' to assert a response is a 500 — for example HttpSendFileTest.testSendFileWithFailure expects it when sending a file that cannot be served (missing/unreadable file leads the server to fail the response with 500). It represents an unexpected server-side failure.

Source

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

  /**
   * 429 Too Many Requests (RFC6585)
   */
  HttpResponseExpectation SC_TOO_MANY_REQUESTS = status(429);

  /**
   * 431 Request Header Fields Too Large (RFC6585)
   */
  HttpResponseExpectation SC_REQUEST_HEADER_FIELDS_TOO_LARGE = status(431);

  /**
   * Any 5XX server error
   */
  HttpResponseExpectation SC_SERVER_ERRORS = status(500, 600);

  /**
   * 500 Internal Server Error
   */
  HttpResponseExpectation SC_INTERNAL_SERVER_ERROR = status(500);

  /**
   * 501 Not Implemented
   */
  HttpResponseExpectation SC_NOT_IMPLEMENTED = status(501);

  /**
   * 502 Bad Gateway
   */
  HttpResponseExpectation SC_BAD_GATEWAY = status(502);

  /**
   * 503 Service Unavailable
   */
  HttpResponseExpectation SC_SERVICE_UNAVAILABLE = status(503);

  /**
   * 504 Gateway Timeout

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect server logs/stack trace for the underlying exception that produced the 500 — fix the root cause, not the status.
2. Validate server-side inputs before failing: check file existence (vertx.fileSystem().existsBlocking) before sendFile and respond 404 instead of failing.
3. Wrap handler logic with error handling (ctx.fail maps to 500; use ctx.response().setStatusCode(...) for intended errors).
4. If testing intentional failure, keep expecting(SC_INTERNAL_SERVER_ERROR); otherwise expect SC_OK or SC_SUCCESSFUL.

Example fix

// before
ctx.request().sendFile("missing.txt"); // handler throws -> 500
// after
if (vertx.fileSystem().existsBlocking("missing.txt")) {
  ctx.request().sendFile("missing.txt");
} else {
  ctx.response().setStatusCode(404).end();
}

if (!vertx.fileSystem().existsBlocking(path)) {
  throw new NoSuchFileException(path); // avoid server-side 500 from sendFile on missing file
}

boolean is500(HttpClientResponse resp) { return resp.statusCode() == 500; }

client.request(requestOptions)
  .compose(HttpClientRequest::send)
  .expecting(HttpResponseExpectation.SC_OK)
  .onFailure(err -> { if (isCauseStatus(err, 500)) inspectServerLogsForRootCause(); });

When it happens

Trigger: Server-side failure while handling a request: in Vert.x, responding via ctx.fail(...) or an exception in a handler produces a 500. Test usage: client.request(requestOptions).compose(HttpClientRequest::send).expecting(SC_INTERNAL_SERVER_ERROR) when the send-file source file is missing so the server handler fails.

Common situations: Unhandled exceptions in server handlers; missing files or broken resources on the server (e.g. sendFile on a nonexistent path); NPEs from bad configuration; dependency (database/service) failures surfacing as 500.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• Head already written
• size must be > 0
• maxExecuteTime must be > 0
• Unit must not be null
• Result is already complete

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