How to fix ERR value is not an integer or out of range in Redis

What this error means

Redis stores all values as strings internally, but integer operations (INCR, DECR, INCRBY, HINCRBY, DECRBY) interpret those strings as base-10 64-bit signed integers. When Redis attempts to parse the stored value as an integer and fails, it returns this error. The error occurs in two scenarios: 1. **Type mismatch**: The stored value cannot be parsed as an integer at all. For example, storing "hello world" or a JSON object and then trying to increment it causes this error. 2. **Range overflow**: The value exceeds the limits of a 64-bit signed integer (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807). Attempting to increment a value already at the maximum causes this error. 3. **Floating-point values**: If you store a decimal like "3.14" and attempt INCR (which is for integers only), Redis rejects it because INCR cannot represent the result as an integer. This error is critical because it indicates the data model or input validation in your application does not match Redis's expectations for integer storage.

Typical symptoms

• INCR, DECR, or INCRBY commands fail with "ERR value is not an integer or out of range"
• HINCRBY, HINCRBYFLOAT, or ZINCRBY operations on hash fields or sorted set scores fail unexpectedly
• Counters in your application stop working after processing certain data
• Rate limiting logic fails when trying to increment a counter
• Session or cache expiration time validation fails with this error
• Application logs show the error occurring sporadically, often after data migrations or format changes
• Lua scripts using tonumber() or integer arithmetic fail in Redis 7.2+

Common causes

1. Storing non-numeric strings (like "hello", "null", or JSON) and attempting to increment them
2. Attempting INCR on floating-point decimal values like "3.14" (use INCRBYFLOAT instead)
3. A counter exceeds 64-bit signed integer limits after repeated increments
4. Setting a value via SET or other commands with a format incompatible with integer operations
5. Race condition where multiple clients set different value types to the same key
6. Expiration values (EX, PX parameters) passed as null, undefined, or non-integer values
7. Invalid database index in Redis connection string (e.g., "redis://host:6379/invalid_db_name")
8. Lua script passing non-integer or out-of-range values to HINCRBY or similar commands
9. Redis 7.2+ behavior change affecting Lua scripts with large numeric values (n * 100,000,000)

How to fix "ERR value is not an integer or out of range"

# Connect to Redis CLI:
redis-cli

# Check the value type and content:
TYPE mykey
GET mykey

# For hash fields:
HGET myhash field
TYPE myhash

# For sorted sets:
ZSCORE myzset member

# Set to a valid integer:
SET mykey 0

# Then increment:
INCR mykey
# Returns: (integer) 1

# For hashes:
HSET myhash field 0
HINCRBY myhash field 5
# Returns: (integer) 5

# Store a decimal:
SET price 3.14

# INCR fails:
INCR price
# Error: ERR value is not an integer or out of range

# Use INCRBYFLOAT instead:
INCRBYFLOAT price 0.5
# Returns: "3.64"

# INCRBYFLOAT works with both integers and floats:
INCRBYFLOAT price 2
# Returns: "5.64"

# Check the current value:
GET mycounter

# If approaching 9223372036854775807, you are at the limit:
# Maximum 64-bit signed int: 9223372036854775807
# Minimum 64-bit signed int: -9223372036854775808

# If overflow is a concern, reset the counter:
DEL mycounter
SET mycounter 0

# Or use a different key naming strategy with timestamp:
SET counter:2025:12:25 0

# Correct format (db index is 0, 1, 2, etc.):
redis://localhost:6379/0
redis://localhost:6379/1

# Incorrect format (non-numeric db name):
redis://localhost:6379/robotix_max_bot  # Wrong!

# Fix by either:
# 1. Remove the invalid db name:
redis://localhost:6379
# This defaults to db 0

# 2. Or explicitly pass db parameter:
redis://localhost:6379?db=0

// Node.js example:
const redis = require("redis");
const client = redis.createClient();

// Before setting a counter:
function setCounter(key, value) {
  if (!Number.isInteger(value)) {
    throw new Error("Counter must be an integer");
  }
  if (value < -9223372036854775808 || value > 9223372036854775807) {
    throw new Error("Value exceeds 64-bit signed integer limits");
  }
  return client.set(key, value.toString());
}

// Safe increment:
async function safeIncrement(key) {
  const value = await client.get(key);
  if (value === null) {
    return client.set(key, "1");
  }
  if (!/^-?\d+$/.test(value)) {
    throw new Error(`Invalid integer in key ${key}: ${value}`);
  }
  return client.incr(key);
}

-- Problematic pattern in Redis 7.2+ when ARGV[1] matches n * 100,000,000:
local increment = tonumber(ARGV[1])  -- May fail for certain numeric patterns
redis.call('HINCRBY', KEYS[1], KEYS[2], increment)

-- Safer approach: validate and handle the conversion explicitly:
local increment = ARGV[1]
if type(increment) == "string" then
  increment = tonumber(increment)
end

if increment == nil or (increment % 1 ~= 0) then
  error("INVALIDARG Increment must be an integer")
end

return redis.call('HINCRBY', KEYS[1], KEYS[2], increment)

Advanced notes

Frequently asked questions

What does "ERR value is not an integer or out of range" mean?

Redis stores all values as strings internally, but integer operations (INCR, DECR, INCRBY, HINCRBY, DECRBY) interpret those strings as base-10 64-bit signed integers. When Redis attempts to parse the stored value as an integer and fails, it returns this error. The error occurs in two scenarios: 1.

How do I fix "ERR value is not an integer or out of range"?

The Redis error "ERR value is not an integer or out of range" occurs when integer operations (INCR, DECR, INCRBY, HINCRBY, etc.) receive invalid values. This happens when the stored value is not a valid integer, exceeds 64-bit signed integer limits, or is a floating-point number. Fixing requires storing valid integers, using INCRBYFLOAT for decimals, or validating input before operations.

What causes "ERR value is not an integer or out of range"?

Storing non-numeric strings (like "hello", "null", or JSON) and attempting to increment them Attempting INCR on floating-point decimal values like "3.14" (use INCRBYFLOAT instead) A counter exceeds 64-bit signed integer limits after repeated increments

Is the "ERR value is not an integer or out of range" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• WRONGPASS invalid username-password pair

  WRONGPASS invalid username-password pair in Redis

  HIGH

• TRYAGAIN Multiple keys request during rehashing

  TRYAGAIN Multiple keys request during rehashing in Redis

  MEDIUM

• ERR WRONGTYPE Operation against a key holding the wrong kind of value

  How to fix "WRONGTYPE Operation against a key holding the wrong kind of value" in Redis

  MEDIUM

• +try-failover: New failover in progress

  How to fix "+try-failover: New failover in progress" in Redis

  MEDIUM

• LOADING Redis is loading the dataset in memory

  How to fix 'LOADING Redis is loading the dataset in memory' error

  MEDIUM

• NOAUTH Authentication required

  NOAUTH Authentication required in Redis

  MEDIUM

Official resources & further reading

• 📚Redis Official Documentation
• 📖
  Redis Official Docs - INCR Command(Official Docs)
• 📖
  Redis Official Docs - INCRBY Command(Official Docs)
• 📖
  Redis Official Docs - INCRBYFLOAT Command(Official Docs)
• node-redis Issue #1505 - ERR value is not an integer
• Database.Guide - Fixing ERR value is not an integer in HRANDFIELD