How to fix ERR offset is out of range in Redis

RedisINTERMEDIATEMEDIUMUpdated Dec 29, 2025· 179 views

The offset value exceeds Redis string size limits (max 536,870,911 bytes). Verify offset is within bounds and your string doesn't exceed 512MB.

Quick fix

Fixes ERR offset is out of range

const MAX_OFFSET = 536870911; // 2^29 - 1
if (offset > MAX_OFFSET) {
  throw new Error(`Offset ${offset} exceeds maximum allowed ${MAX_OFFSET}`);
}
  1. Verify the offset value is within bounds
  2. Check the current string size
  3. Consider using multiple keys for large data
  4. Use alternative data structures if appropriate
redis — error
const MAX_OFFSET = 536870911; // 2^29 - 1
if (offset > MAX_OFFSET) {
  throw new Error(`Offset ${offset} exceeds maximum allowed ${MAX_OFFSET}`);
}
ERR offset is out of range

What this error means

This error occurs when you attempt to use an offset value that exceeds the maximum allowed offset for Redis string operations. Redis strings have a maximum size of 512 megabytes, which corresponds to a maximum offset of 2^29 - 1 (536,870,911 bytes). This limit applies to commands like SETRANGE, GETRANGE, and SETBIT. When you try to access or modify a string at an offset beyond this limit, Redis rejects the operation and returns this error to prevent memory allocation problems.

Typical symptoms

  • SETRANGE, GETRANGE, or SETBIT operations fail with "ERR offset is out of range"
  • Attempting to write to very large offsets (> 536MB) in a string key
  • Application receives error when trying to manipulate string data at high byte positions
  • CI/CD pipelines fail when using string-based caching beyond memory limits

Common causes

  1. Offset value exceeds 536,870,911 (the maximum offset for Redis strings)
  2. String key is approaching or has exceeded the 512MB size limit
  3. Attempting to SETRANGE with an offset that would require allocating memory beyond the string size limit
  4. Using negative offsets with SETRANGE (SETRANGE does not support negative offsets)
  5. Incorrect offset calculation in your application code

How to fix "ERR offset is out of range"

1Verify the offset value is within bounds

Check that your offset does not exceed 536,870,911 (2^29 - 1). If you're calculating the offset programmatically, add validation:

javascript
const MAX_OFFSET = 536870911; // 2^29 - 1
if (offset > MAX_OFFSET) {
  throw new Error(`Offset ${offset} exceeds maximum allowed ${MAX_OFFSET}`);
}
2Check the current string size

Use the STRLEN command to check how large the string currently is:

bash
redis-cli STRLEN your_key

If the string is already large and you're trying to write even further, consider using multiple keys or a different data structure.

3Consider using multiple keys for large data

Instead of storing everything in a single Redis string, split your data across multiple keys:

javascript
// Instead of: SET huge_string with 1GB of data
// Use: SET huge_string:chunk_0, huge_string:chunk_1, etc.
const chunkSize = 100 * 1024 * 1024; // 100MB chunks
const chunkIndex = Math.floor(offset / chunkSize);
const offsetInChunk = offset % chunkSize;
const key = `your_key:chunk_${chunkIndex}`;
// Now use offsetInChunk which will be < 100MB
4Use alternative data structures if appropriate

If you don't actually need the offset-based string operations, consider using a different Redis data structure:

javascript
// For large ordered data: Use Sorted Sets
redis.ZADD("my_sorted_set", score, member);

// For large key-value pairs: Use Hashes
redis.HSET("my_hash", field, value);

// For large lists: Use Lists
redis.LPUSH("my_list", item);
5Ensure you're not using negative offsets with SETRANGE

SETRANGE does not support negative offsets (unlike GETRANGE). Always use positive offsets:

javascript
// Correct:
redis.SETRANGE("my_key", 100, "value");

// Incorrect:
redis.SETRANGE("my_key", -1, "value"); // This will error

If you need to work from the end of a string, use GETRANGE (which supports negative offsets) to read the data, or calculate the positive offset manually.

Advanced notes

The 512MB limit on Redis strings is a hard limit in the Redis server. This is by design to prevent excessive memory allocation which can block the server for extended periods (allocating 512MB can take ~300ms on modern hardware). For truly massive datasets, consider using Redis streams, sorted sets with individual members, or external storage like S3. When using SETRANGE to create sparse strings (writing to high offsets in empty keys), Redis will pre-allocate all memory up to that offset, which can cause server blocking. Use GETRANGE with negative offsets to read from the end of strings since it supports negative indexing (e.g., -1 for the last byte, -2 for the penultimate byte), whereas SETRANGE does not support negative offsets.

Frequently asked questions

What does "ERR offset is out of range" mean?
This error occurs when you attempt to use an offset value that exceeds the maximum allowed offset for Redis string operations. Redis strings have a maximum size of 512 megabytes, which corresponds to a maximum offset of 2^29 - 1 (536,870,911 bytes). This limit applies to commands like SETRANGE, GETRANGE, and SETBIT.
How do I fix "ERR offset is out of range"?
The offset value exceeds Redis string size limits (max 536,870,911 bytes). Verify offset is within bounds and your string doesn't exceed 512MB.
What causes "ERR offset is out of range"?
Offset value exceeds 536,870,911 (the maximum offset for Redis strings) String key is approaching or has exceeded the 512MB size limit Attempting to SETRANGE with an offset that would require allocating memory beyond the string size limit
Is the "ERR offset is out of range" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading