なぜこのエラーが発生するのか
ユーザーのアクティビティ追跡や機能フラグの管理のために SETBIT や GETBIT コマンドを実行している際、Redisが突然操作をブロックすることがあります。ERR bit offset is not an integer or out of range というエラーメッセージは、指定したオフセット値が数学的に不可能であるか、Redisエンジンのアーキテクチャ上の制限を超えていることを示しています。
Redisのビットマップは技術的には文字列（String）として保存されるため、最大文字列サイズ制限である512MBを継承します。この制約によって、単一のキーで操作できるビット数が厳密に決まっています。
3つの主な原因
ほとんどの開発者がこの壁にぶつかる理由は、以下の3つのいずれかに集約されます。原因を特定することが解決への第一歩です。
1. 512MBのハードリミット
Redisの文字列は512MBを超えることができません。1バイトは8ビットなので、計算は単純です。512 × 1024 × 1024 × 8 = 4,294,967,296 ビット。つまり、許容される最大オフセットは 4,294,967,295 (2^32 - 1) です。アプリケーションがユーザーID「50億」などをオフセットとして使用しようとすると、Redisは即座にこれを拒否します。
2. 無効なデータ型
オフセットは非負の整数である必要があります。コード内で誤って浮動小数点数、null値、または負の整数を渡している可能性があります。例えば、計算結果が 1024.5 や NaN になった場合、Redisはどのビットを操作すべきか判断できず、このエラーをスローします。
3. メモリ割り当ての失敗
高いオフセットでビットを設定すると、Redisはそのビットに到達するまでのすべてのメモリを割り当てる必要があります。新しいキーに対して SETBIT mykey 2000000000 1 を実行すると、Redisは瞬時に約250MBのRAMを確保しようとします。サーバーのメモリが不足しているか、redis.conf の maxmemory 制限に達している場合、割り当てに失敗し、範囲外（out-of-range）エラーとして現れることがあります。
即時のトラブルシューティング
オフセットを手動でテストする
redis-cli を使用して、オフセットが42.9億の制限内にあるか確認してください。比較することで、問題が値自体にあるのか、それともアプリケーションのロジックにあるのかを切り分けることができます。
# 成功例: 1MBのオフセット
SETBIT login_tracker 1048576 1
# 失敗例: 2^32 - 1 の制限を超過
SETBIT login_tracker 5000000000 1
入力をクリーンにする
クライアントライブラリに送る前に、必ずオフセットを絶対整数にキャストしてください。JavaScriptを使用している場合は Math.floor() や parseInt() が有効です。Pythonの場合は、除算操作から float が渡されていないか確認してください。
長期的な解決策
1. ビットマップ・シャッディングの実装
IDが42億を超える場合、単一のキーを使用することはできません。代わりに、データを複数のキーに分割します。この「シャッディング」と呼ばれる手法により、個々のキーを小さく管理可能なサイズに保つことができます。
以下は単純なロジックのパターンです：
# 例: ターゲットIDが 5,000,000,000
# シャードごとに100万ビットを割り当てたい場合
ID = 5000000000
SHARD_SIZE = 1000000
shard_number = ID // SHARD_SIZE
local_offset = ID % SHARD_SIZE
# 生成されるコマンドのイメージ: SETBIT activity:shard:5000 0 1
redis.setbit(f"activity:shard:{shard_number}", local_offset, 1)
2. スパースなデータには Set 型へ切り替える
少数のユーザーのために高いオフセットを使用していませんか？ビットマップは、データが疎（スパース）な場合にはメモリを大量に消費します。ビット 4,000,000,000 を設定すると、たとえ1ビットしか立っていなくても500MBのRAMを使用します。データが分散している場合は、代わりに Redis Set (SADD) を使用してください。実際に提供されたIDのみを保存するため、メモリを大幅に節約できます。
3. メモリ負荷の監視
Redisに拡張の余地があるか、現在のメモリステータスを確認してください。ターミナルで INFO memory を実行します。特に used_memory_human と maxmemory_human に注目してください。制限に近い場合、Redisはビットマップ文字列を新しい高いオフセットまで拡張することを拒否することがあります。
最終確認
修正が機能しているか確認するために、キーの型と範囲を検証します。TYPE <key> で文字列であることを確認し、STRLEN <key> で現在のバイト数を確認します。長さが 536,870,912 バイトに達している場合は、絶対的な上限に達しています。その時点では、シャッディングは選択肢ではなく必須事項となります。