eclipse-vertx/vert.x · warning

416 Requested Range Not Satisfiable

Error message

416 Requested Range Not Satisfiable

What it means

SC_REQUESTED_RANGE_NOT_SATISFIABLE is the HttpResponseExpectation constant for HTTP 416 Range Not Satisfiable. Vert.x exposes it for response validation; a 416 failing this expectation reports '416 Requested Range Not Satisfiable'. The client sent a Range header requesting bytes outside the size of the representation (e.g. start offset beyond end-of-file), so the server rejected it.

Source

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

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

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

  /**
   * 423 Locked (WebDAV, RFC4918)

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check the resource size first (HEAD request / Content-Length) and clamp the Range to offset < size
2. Validate the resume state: if the local partial file is longer than the remote resource, restart the download from scratch
3. Handle 416 as 'download complete' when the offset equals the content length
4. Format the Range header correctly: bytes=<start>-<end> with start <= end
5. Compare ETag/Last-Modified between resume attempts to detect a changed resource

Example fix

// before
request.putHeader("Range", "bytes=" + localOffset + "-"); // may exceed remote size -> 416
// after
long remoteSize = /* via HEAD Content-Length */;
if (localOffset >= remoteSize) {
  // nothing to download
} else {
  request.putHeader("Range", "bytes=" + localOffset + "-");
}

// Clamp the resume offset to the remote size
long remoteSize = fetchContentLengthViaHead(uri);
if (localOffset > remoteSize) { restartDownload(); }
else if (localOffset == remoteSize) { markComplete(); }
else { request.putHeader("Range", "bytes=" + localOffset + "-"); }

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

if (isRangeNotSatisfiable(t)) { if (offsetAtRemoteEnd()) markComplete(); else restartDownload(); }

When it happens

Trigger: Resuming or throttling a download via Vert.x HttpClient with a Range header whose start offset is >= the resource size, or a stale saved offset after the remote file changed/shrank, or a malformed Range value (e.g. bytes=0- not intended, bytes=10-5 inverted).

Common situations: Resumable download logic resuming past EOF, remote file replaced by a smaller version between attempts, off-by-one in byte offsets, proxies stripping multi-range support, using Range against endpoints that don't support it (should be 416/ignored per 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

• size must be > 0
• maxExecuteTime must be > 0
• Unit must not be null
• Result is already complete
• Promise already completed

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