eclipse-vertx/vert.x · info · NullPointerException

Unit must not be null

Error message

Unit must not be null

What it means

SC_SERVICE_UNAVAILABLE is an HttpResponseExpectation constant asserting an HTTP 503 status. It is a validation handle, not a thrown error; the '503 Service Unavailable' message appears when an expectation check against it fails (or when code maps a 503 response for reporting).

Source

Thrown at vertx-core/src/main/java/io/vertx/core/Future.java:783

   * @throws IllegalStateException when the current thread must be parked and this method is called from a Vert.x event-loop or worker thread.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  default T await(Duration timeout) throws TimeoutException {
    return await(timeout.toMillis(), TimeUnit.MILLISECONDS);
  }

  /**
   * Like {@link #await()} but with a timeout.
   *
   * @param timeout the timeout
   * @param unit the timeout unit
   * @return the result when this {@link Future} is completed
   * @throws TimeoutException when the timeout fires before the future completes
   * @throws IllegalStateException when the current thread must be parked and this method is called from a Vert.x event-loop or worker thread.
   */
  default T await(long timeout, TimeUnit unit) throws TimeoutException {
    if (unit == null) {
      throw new NullPointerException("Unit must not be null");
    }
    CountDownLatch continuation = trySuspend();
    if (continuation != null) {
      try {
        if (!continuation.await(timeout, unit)) {
          throw new TimeoutException();
        }
      } catch (InterruptedException e) {
        Utils.throwAsUnchecked(e);
        return null;
      }
    }
    return getOrFail();
  }

  /**
   * Calls {@link #await()} on {@code future}.
   *

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Retry the request with backoff since 503 usually indicates temporary unavailability (check Retry-After header).
2. If a success was expected, address server capacity/health so it stops returning 503.
3. Keep SC_SERVICE_UNAVAILABLE only where 503 is the intended contract; otherwise replace with the appropriate status expectation.

Example fix

// before
request.expect(HttpResponseExpectation.SC_SERVICE_UNAVAILABLE).send();
// after
request.expect(HttpResponseExpectation.SC_OK).send();

if (response.statusCode() == 503) {
  long waitMs = response.getHeader("Retry-After") != null ? Long.parseLong(response.getHeader("Retry-After")) * 1000 : 1000;
  // schedule retry after waitMs
}

When it happens

Trigger: Using request.expect(HttpResponseExpectation.SC_SERVICE_UNAVAILABLE) with a response whose status is not 503; matching responses with status 503 during overload/maintenance.

Common situations: A backend under load or in maintenance returns 503 while the caller expected success; retry/circuit-breaker tests that intentionally return 503; service mesh signaling temporary unavailability.

Related errors

• size must be > 0
• maxExecuteTime must be > 0
• code: <statusCode> (expected: 0+)
• 429 Too Many Requests (RFC6585)
• Result is already complete

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