🚨 Redis Error Guide: 'increment or decrement would overflow' — Fix 64-bit Counter Overflows

Overview

Redis returns this error when an integer counter command (INCR, INCRBY, DECR, DECRBY, HINCRBY) would push the value past the range of a signed 64-bit integer. Redis stores these counters as int64, so the value must stay within -9223372036854775808 .. 9223372036854775807. Any operation that would cross either bound is rejected rather than silently wrapping.

The literal error clients receive:

(error) ERR increment or decrement would overflow

A closely related message, ERR increment would produce NaN or Infinity, comes from the floating-point variants (INCRBYFLOAT, HINCRBYFLOAT). This guide focuses on the integer overflow: it means the counter design allows values larger than 64 bits can hold, or a single INCRBY argument is itself enormous.

Symptoms

• INCR/INCRBY/HINCRBY on a specific key suddenly fails while smaller counters work fine.
• The counter’s current value is already near 9.2e18 (the int64 max).
• A single INCRBY key <huge-number> fails immediately even on a fresh key.

redis-cli SET counter 9223372036854775807
redis-cli INCR counter

(error) ERR increment or decrement would overflow

Common Root Causes

1. The counter reached the int64 ceiling

A long-lived, high-rate counter genuinely accumulated past 9223372036854775807.

redis-cli GET counter

"9223372036854775807"

2. A single oversized increment argument

The INCRBY amount itself exceeds int64 range, or added to the current value crosses the bound.

redis-cli INCRBY counter 99999999999999999999

(error) ERR value is not an integer or out of range

(An argument outside int64 range reports “not an integer or out of range”; a valid argument that pushes past the bound reports “would overflow”.)

3. Misused counter as an ID with a huge seed

Someone seeded a counter with an already-near-max value (e.g. a timestamp in nanoseconds multiplied up), leaving little headroom.

4. BITFIELD with default WRAP masking, then a signed op elsewhere

Packed BITFIELD counters wrap by default; mixing them with INCR semantics can surface unexpected overflow behavior.

Diagnostic Workflow

Step 1: Read the current value and how close it is to the limit

redis-cli GET counter
redis-cli TYPE counter

Compare to the int64 max 9223372036854775807.

Step 2: Confirm the increment argument is sane

# The amount must itself fit in int64
echo "9223372036854775807"   # max

If the app computes the increment, log the exact value being sent.

Step 3: Inspect hash-field counters

redis-cli HGET stats total
redis-cli HINCRBY stats total 1

Step 4: For packed counters, check BITFIELD overflow mode

# SAT saturates at the type max instead of wrapping/erroring; FAIL returns nil
redis-cli BITFIELD counters:u42 OVERFLOW SAT INCRBY u32 0 1

Step 5: Read the logs for the offending command

sudo journalctl -u redis-server --no-pager | grep -iE 'overflow|INCR' | tail

Example Root Cause Analysis

An analytics service uses INCRBY events:total <batch_size> to accumulate lifetime event counts. After a backfill job, writes start failing with ERR increment or decrement would overflow. The current value is inspected:

redis-cli GET events:total

"9223372036854772100"

The counter is a few thousand short of the int64 maximum. The root cause is design, not a bug: a single lifetime counter was never going to fit the traffic once a backfill replayed years of events at once, and it hit the 64-bit ceiling.

The fix was to stop tracking an unbounded lifetime total in one int64 and instead bucket the counter by time window, so no single field can overflow:

# Per-day fields; sum in the app when a total is needed
redis-cli HINCRBY events:2026-07-09 total 5000
redis-cli EXPIRE events:2026-07-09 7776000   # 90-day retention

For the corrupted lifetime key, the team reset it to a correct current baseline computed from the source of truth, then switched all writers to the bucketed scheme. No writer can approach int64 range within a bucket’s lifetime.

Prevention Best Practices

• Design counters so no single field can realistically reach 9.2e18: bucket by time window, shard across keys, or reset/rotate periodically.
• Validate app-computed increment amounts before sending them; a runaway INCRBY argument is a common trigger.
• Use BITFIELD ... OVERFLOW SAT (saturate) or OVERFLOW FAIL (return nil) when you want defined behavior at the type boundary instead of an error.
• Never seed counters with near-max values (raw nanosecond timestamps, multiplied ids) — leave headroom.
• Monitor high-rate counters and alert when they approach the int64 ceiling, well before writes start failing.
• Feed the failing command into the free incident assistant, and browse more Redis guides.

Quick Command Reference

# How close is the counter to the int64 max (9223372036854775807)?
redis-cli GET counter
redis-cli TYPE counter

# Hash-field counter
redis-cli HINCRBY stats total 1

# Packed counters with defined overflow behavior
redis-cli BITFIELD counters:u42 OVERFLOW SAT INCRBY u32 0 1
redis-cli BITFIELD counters:u42 OVERFLOW FAIL INCRBY u32 0 1

# Bucketed design to avoid overflow
redis-cli HINCRBY events:2026-07-09 total 5000

Conclusion

increment or decrement would overflow means an integer counter would cross the signed 64-bit boundary. The typical root causes are:

1. A long-lived, high-rate counter that genuinely reached the int64 ceiling.
2. An oversized INCRBY/DECRBY argument.
3. A counter seeded with a value that already left no headroom.

Redis is protecting you from a silent wrap. The durable fix is to redesign the counter so no single int64 field can reach the limit — bucket by time, shard, or rotate — and to use BITFIELD OVERFLOW SAT/FAIL where you want defined saturation instead of an error.