InvalidRange
Amazon S3 InvalidRange means a `GetObject` byte range request cannot be satisfied by the current object length or selected object version.
Last reviewed: April 27, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Invalid Range Mean?
The object exists, but the requested byte interval is outside the bytes available for the current object. Most incidents come from stale content length, off-by-one math, zero-byte objects, media seek logic, parallel chunk planning, or an object being replaced with a smaller version after ranges were calculated.
Common Causes
- -Range end is calculated as
ContentLengthinstead ofContentLength - 1for zero-based byte ranges. - -Client requests a range for a cached object size after the object was overwritten with a shorter version.
- -Downloader or video player requests a suffix or seek range that is larger than a small or empty object.
- -Parallel download planner creates final chunks without clamping the last byte to the current object length.
- -Range request omits ETag/version pinning, so metadata and content can drift between planning and read.
How to Fix Invalid Range
- 1Run
HeadObjectimmediately before range planning and derive valid bytes as0throughContentLength - 1. - 2Skip range reads for zero-byte objects and handle them as empty payloads.
- 3Clamp the final chunk end byte to
ContentLength - 1and use open-ended ranges likebytes=start-when appropriate. - 4Use
If-Matchor explicit version IDs when downloading chunks planned from a specific object state. - 5If the object changed, discard the old range plan and rebuild chunks from current metadata.
Step-by-Step Diagnosis for Invalid Range
- 1Capture bucket, key, version ID,
Rangeheader, response status, request ID, and caller from the failedGetObject. - 2Compare the requested start/end bytes with current
HeadObjectContentLength, ETag, Last-Modified, and version ID. - 3Check whether the object was overwritten, compacted, transcoded, or replaced between range planning and read execution.
- 4Inspect media/player or parallel download chunk logic for off-by-one, suffix-range, and final-chunk clamp bugs.
- 5Replay with the exact failing range, then with an open-ended or clamped range to prove the boundary calculation.
Seen in Production
- -A video player seeks to the end of a newly uploaded small preview and requests a byte range beyond the current object length.
- -A parallel downloader plans 8 MB chunks from stale metadata, then the object is replaced by a compressed smaller version.
- -A final-chunk bug requests
bytes=0-1024for a 1024-byte object instead ofbytes=0-1023. - -A range reader attempts
bytes=0-0against a zero-byte object and treats the 416 as a transient S3 error.
Range Math and Object Metadata Audit
- -Validate range math with current
ContentLength: valid closed byte offsets are0throughContentLength - 1. - -Compare range-planning metadata with the object ETag/version used by actual chunk reads.
Streaming and Parallel Download Controls
- -Clamp suffix, seek, and final-chunk requests for small objects.
- -Pin chunk reads with
If-Matchor version ID when object replacement is possible during the download window.
Decision Shortcut: Range Bug vs Object Drift
- -If the same range is impossible for the current length, fix range math or empty-object handling.
- -If the range was valid for an earlier ETag/version, rebuild the plan from current object metadata.
- -If the object itself is absent, move to NoSuchKey before debugging range boundaries.
Wrong Fix to Avoid
- -Do not retry the same impossible byte range without recalculating current object length.
- -Do not assume S3 range support is broken when the final byte equals object size instead of size minus one.
- -Do not remove validator pinning if concurrent object replacement is the real cause.
Implementation Examples
2026-04-27T11:25:08Z bucket=media-prod key=video/intro.mp4
range="bytes=10485760-12582911" contentLength=10485760 status=416 error=InvalidRange
message="The requested range cannot be satisfied"SIZE=$(aws s3api head-object \
--bucket media-prod \
--key video/intro.mp4 \
--query 'ContentLength')
SAFE_END=$((SIZE - 1))
aws s3api get-object \
--bucket media-prod \
--key video/intro.mp4 \
--range bytes=0-$SAFE_END \
output.partasync function getSafeRange(bucket, key, start, chunkSize) {
const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
const length = head.ContentLength ?? 0;
if (length === 0 || start >= length) {
return null;
}
const end = Math.min(start + chunkSize - 1, length - 1);
return s3.send(new GetObjectCommand({
Bucket: bucket,
Key: key,
Range: `bytes=${start}-${end}`,
IfMatch: head.ETag,
}));
}Incident Timeline
11:24 UTC
Client plans byte ranges from stale or incorrect metadata
Signal: Chunk planner, media player, or SDK cache computes offsets from old content length or off-by-one logic.
Why it matters: The first useful question is whether the requested interval can exist for the current object.
11:25 UTC
S3 rejects the request with InvalidRange
Signal: GetObject receives a Range header outside the satisfiable byte interval.
Why it matters: The object exists; the byte boundary does not.
11:27 UTC
Retries repeat the same unsatisfiable interval
Signal: Download workers replay the same final chunk or seek range and fail deterministically.
Why it matters: Backoff does not help until range math or object metadata is refreshed.
11:34 UTC
Ranges are recalculated from current object state
Signal: The planner reloads ContentLength/ETag/version and clamps or skips invalid ranges.
Why it matters: That confirms the failure lived in byte planning or object drift.
Seen in Production
Video Player Seek Error
Frequency: high
Example: A user tries to skip to the end of a 50MB video. The player requests bytes=50000000-51000000. Because the file ends at 49,999,999, S3 throws InvalidRange.
Fix: Use the open-ended range bytes=49000000- to let S3 handle the termination point.
Parallel downloader final chunk is not clamped
Frequency: common
Example: Chunk planner requests one full 8 MB chunk beyond the object end after integer division rounds up.
Fix: Clamp the final range end to ContentLength - 1 and skip empty intervals.
Object is replaced with smaller compressed output
Frequency: medium
Example: Workers planned chunks from the original file, but a compaction job replaced it with a shorter object before reads finished.
Fix: Pin reads to version ID or ETag, or restart the range plan after replacement.
Wrong Fix vs Better Fix
Retry same range vs recompute bounds
Wrong fix: Replay the exact Range header with exponential backoff.
Better fix: Fetch current ContentLength and rebuild the requested interval before retrying.
Why this is better: An unsatisfiable range remains invalid until object length or request boundaries change.
Hardcode chunk size vs clamp final chunk
Wrong fix: Generate fixed-size chunks and assume the final chunk has the same length.
Better fix: Clamp the final byte to ContentLength - 1 and skip ranges for zero-byte objects.
Why this is better: Final chunks and empty objects are where most range math bugs surface.
Ignore object replacement vs pin validators
Wrong fix: Plan ranges once and read chunks later without checking whether the object changed.
Better fix: Use ETag/version pinning or discard the plan when HeadObject metadata changes.
Why this is better: Range plans are only valid for the exact object state they were computed from.
Debugging Tools
- -aws s3api head-object
- -S3 server access logs
- -CDN range-request logs
- -Browser or player network traces
How to Verify the Fix
- -Trigger
GetObjectwith ranges strictly within0toContentLength - 1and confirm206 Partial Content. - -Verify returned
Content-Range,Content-Length, ETag, and version ID match the planned chunk. - -Test zero-byte, one-byte, small-object, suffix-range, final-chunk, and overwritten-object cases.
- -Confirm InvalidRange rates drop in application logs, CDN logs, and S3 access logs.
How to Prevent Recurrence
- -Centralize range planning in one helper that validates
start,end,ContentLength, and empty-object behavior. - -Pin range downloads to an ETag or version ID when object replacement can happen during reads.
- -Add tests for off-by-one, suffix ranges, zero-byte objects, and final-chunk clamping.
- -Emit structured telemetry for requested range, current length, ETag/version, and planner source.
Pro Tip
- -use
bytes=start-for tail reads when the end byte does not matter, but still rejectstart >= ContentLengthbefore dispatch.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.