InvalidRange

What Does Invalid Range Mean?

InvalidRange is S3's way of saying: "You are asking for data that does not exist at that position." If an object is 100 bytes and you request bytes=100-200, S3 returns this error. It is most common in parallel download managers and video players that attempt to "pre-fetch" chunks of a file before its total length is verified or if the file was overwritten with a smaller version during the process.

Common Causes

• -Off-by-One Errors: Requesting bytes=0-100 for a 100-byte file (should be 0-99 as ranges are zero-indexed).
• -Empty Files: Attempting any range request on a 0-byte object will always return InvalidRange.
• -Race Conditions: A client requests a range based on a previous version of an object, but the object has since been replaced with a smaller file.
• -Hardcoded Logic: Download managers that assume a fixed chunk size without checking the Content-Length of the target object first.

How to Fix Invalid Range

1. 1Perform a HEAD Request: Call HeadObject first to get the current Content-Length and validate your range before calling GetObject.
2. 2Zero-Index Validation: Ensure your range ends at Length - 1. For a file of size N, the valid range is 0 to N-1.
3. 3Conditional Headers: Use the If-Match header with the object's ETag to ensure you are requesting a range from the exact version of the file you expect.
4. 4Handle 0-byte Objects: Add a conditional check to skip range requests if the object size is zero.

Step-by-Step Diagnosis for Invalid Range

1. 1Check the Content-Length of the object in the S3 console or via CLI to find the actual boundaries.
2. 2Inspect the Range header being sent by the client. Format: bytes=start-end.
3. 3Verify the object has not been updated recently by checking the Last-Modified timestamp in S3 metadata.
4. 4Enable S3 Server Access Logs to see the exact Range string that triggered the 416 error.

# 1. Get the actual size
SIZE=$(aws s3api head-object --bucket my-bucket --key file.mp4 --query 'ContentLength')

# 2. Calculate safe end (Size - 1)
SAFE_END=$((SIZE - 1))

# 3. Perform safe range request
aws s3api get-object --bucket my-bucket --key file.mp4 --range bytes=0-$SAFE_END output.part

const { S3Client, HeadObjectCommand, GetObjectCommand } = require("@aws-sdk/client-s3");

async function downloadSafeRange(bucket, key, start) {
  const head = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
  const totalSize = head.ContentLength;

  if (start >= totalSize) {
    console.error("Start byte is beyond file size!");
    return;
  }

  // Blank end 'start-' is the safest way to avoid InvalidRange
  return client.send(new GetObjectCommand({
    Bucket: bucket,
    Key: key,
    Range: `bytes=${start}-`
  }));
}

How to Verify the Fix

• -Trigger a GetObject with a range that is strictly within 0 to Content-Length - 1.
• -Confirm the response is 206 Partial Content and not 416 Requested Range Not Satisfiable.
• -Verify the returned Content-Range header matches your requested boundaries.

How to Prevent Recurrence

• -Dynamic Range Calculation: Never hardcode byte offsets. Always derive them from the Content-Length returned by a HeadObject call.
• -ETag Locking: When performing multipart downloads, "lock" the version of the file using the If-Match header to prevent race conditions during updates.
• -Sanitize Inputs: In frontend code, ensure that start/end values are integers and that start < end.
• -Pro-tip: If you want to download from a specific point to the end of the file, use bytes=start- (leave the end blank). S3 will automatically return everything from the start point to the actual end of the file, safely avoiding InvalidRange errors.

Related Errors

Decision Support

Official References

• -S3 GetObject API: Range Header
• -HTTP Range Requests (MDN)
• -RFC 9110 Section 14.2 - Range Requests
• -AWS Official Documentation