{"record":{"id":"73b752b4ea7e732a","repo":"eclipse-vertx/vert.x","slug":"416-requested-range-not-satisfiable","errorCode":null,"errorMessage":"416 Requested Range Not Satisfiable","messagePattern":"416 Requested Range Not Satisfiable","errorType":"http","errorClass":null,"httpStatus":416,"severity":"warning","filePath":"vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java","lineNumber":230,"sourceCode":"  /**\n   * 413 Request Entity Too Large\n   */\n  HttpResponseExpectation SC_REQUEST_ENTITY_TOO_LARGE = status(413);\n\n  /**\n   * 414 Request-URI Too Long\n   */\n  HttpResponseExpectation SC_REQUEST_URI_TOO_LONG = status(414);\n\n  /**\n   * 415 Unsupported Media Type\n   */\n  HttpResponseExpectation SC_UNSUPPORTED_MEDIA_TYPE = status(415);\n\n  /**\n   * 416 Requested Range Not Satisfiable\n   */\n  HttpResponseExpectation SC_REQUESTED_RANGE_NOT_SATISFIABLE = status(416);\n\n  /**\n   * 417 Expectation Failed\n   */\n  HttpResponseExpectation SC_EXPECTATION_FAILED = status(417);\n\n  /**\n   * 421 Misdirected Request\n   */\n  HttpResponseExpectation SC_MISDIRECTED_REQUEST = status(421);\n\n  /**\n   * 422 Unprocessable Entity (WebDAV, RFC4918)\n   */\n  HttpResponseExpectation SC_UNPROCESSABLE_ENTITY = status(422);\n\n  /**\n   * 423 Locked (WebDAV, RFC4918)","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java#L212-L248","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Check the resource size first (HEAD request / Content-Length) and clamp the Range to offset < size","Validate the resume state: if the local partial file is longer than the remote resource, restart the download from scratch","Handle 416 as 'download complete' when the offset equals the content length","Format the Range header correctly: bytes=<start>-<end> with start <= end","Compare ETag/Last-Modified between resume attempts to detect a changed resource"],"exampleFix":"// before\nrequest.putHeader(\"Range\", \"bytes=\" + localOffset + \"-\"); // may exceed remote size -> 416\n// after\nlong remoteSize = /* via HEAD Content-Length */;\nif (localOffset >= remoteSize) {\n  // nothing to download\n} else {\n  request.putHeader(\"Range\", \"bytes=\" + localOffset + \"-\");\n}","handlingStrategy":"validation","validationCode":"// Clamp the resume offset to the remote size\nlong remoteSize = fetchContentLengthViaHead(uri);\nif (localOffset > remoteSize) { restartDownload(); }\nelse if (localOffset == remoteSize) { markComplete(); }\nelse { request.putHeader(\"Range\", \"bytes=\" + localOffset + \"-\"); }","typeGuard":"boolean isRangeNotSatisfiable(Throwable t) {\n  return t instanceof VertxHttpResponseException\n    && ((VertxHttpResponseException) t).getResponse().statusCode() == 416;\n}","tryCatchPattern":"if (isRangeNotSatisfiable(t)) { if (offsetAtRemoteEnd()) markComplete(); else restartDownload(); }","preventionTips":["HEAD the resource to get Content-Length before resuming","Compare ETags between attempts to detect changed resources","Format Range as bytes=<start>- with start <= end","Treat offset == size as 'already complete', not an error"],"tags":["http","range","download","offset"],"backgroundTag":"value-out-of-range","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}