eclipse-vertx/vert.x · error · IllegalArgumentException

code: <statusCode> (expected: 0+)

Error message

code: <statusCode> (expected: 0+)

What it means

setStatusCode validates that the given HTTP status code is non-negative (Netty-style precondition). Negative values cannot map to an HttpResponseStatus, so an IllegalArgumentException with the message 'code: <n> (expected: 0+)' is thrown before any state is changed.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerResponseImpl.java:145

      if (handler != null) {
        checkValid();
      }
      exceptionHandler = handler;
      return this;
    }
  }

  @Override
  public int getStatusCode() {
    synchronized (conn) {
      return status.code();
    }
  }

  @Override
  public HttpServerResponse setStatusCode(int statusCode) {
    if (statusCode < 0) {
      throw new IllegalArgumentException("code: " + statusCode + " (expected: 0+)");
    }
    synchronized (conn) {
      checkHeadWritten();
      this.status = HttpResponseStatus.valueOf(statusCode);
      return this;
    }
  }

  @Override
  public String getStatusMessage() {
    synchronized (conn) {
      if (statusMessage == null) {
        return status.reasonPhrase();
      }
      return statusMessage;
    }
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Validate the status code before calling setStatusCode, clamping or defaulting invalid values (e.g. to 500)
2. Replace sentinel negative values with a proper Optional/constant and map to a real HTTP status
3. Only pass literals from the valid HTTP status range (100-599 in practice)

Example fix

// before
int code = errorToStatusCode(err); // may return -1
response.setStatusCode(code); // IllegalArgumentException

// after
int code = errorToStatusCode(err);
response.setStatusCode(code >= 0 ? code : 500);

if (statusCode < 0) {
  statusCode = 500;
}
response.setStatusCode(statusCode);

try {
  response.setStatusCode(code);
} catch (IllegalArgumentException e) {
  response.setStatusCode(500);
}

When it happens

Trigger: Calling response.setStatusCode(negativeNumber), typically from a variable holding an unvalidated error code or an off-by-one/arithmetic result.

Common situations: Mapping internal error codes (e.g. -1 for 'unknown') directly to the response status; computed status values from configuration; int defaults of -1 used as 'unset'.

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

• size must be > 0
• maxExecuteTime must be > 0
• Unit must not be null
• keepAliveTimeout must be >= 0
• Invalid setting

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