microsoft/garnet · error · GarnetException

ERR value is not an integer or out of range.

Error message

ERR value is not an integer or out of range.

What it means

Thrown by the internal Index(long offset) helper when IsValidBitOffset(offset) is false - i.e., the bit offset exceeds MaxOffsetForBitmapLength (512 MiB x 8 - 1, about 4.29e9). The message is the standard Redis error string, so to a RESP client it looks like the familiar integer/range error. Index converts a bit offset to a byte index and rejects out-of-range offsets.

Source

Thrown at libs/server/Resp/Bitmap/BitmapManager.cs:105

                ? MaxOffsetForBitmapLength
                : MaxBitmapPayloadBytes - 1L;

            if (startOffset < -maxOffset)
                startOffset = -maxOffset;
            else if (startOffset > maxOffset)
                startOffset = maxOffset;

            if (endOffset < -maxOffset)
                endOffset = -maxOffset;
            else if (endOffset > maxOffset)
                endOffset = maxOffset;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static int Index(long offset)
        {
            if (!IsValidBitOffset(offset))
                throw new GarnetException("ERR value is not an integer or out of range.");
            return (int)(offset >> 3);
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static int LengthInBytes(long offset)
        {
            if (!TryValidateLengthInBytes(offset, out var lengthInBytes))
                throw new GarnetException("ERR value is not an integer or out of range.");
            return lengthInBytes;
        }

        /// <summary>
        /// Check to see if offset contained by value size
        /// </summary>
        /// <param name="vlen"></param>
        /// <param name="offset"></param>
        /// <returns></returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]

View on GitHub (pinned to 951b0fc683)

Solutions

1. Reduce the requested offset below MaxBitmapPayloadBytes * 8 - 1 (512 MiB x 8 - 1).
2. If you call bitmap internals from extension code, validate the offset with BitmapManager.IsValidBitOffset first.
3. Check that you are on a current Garnet build - older builds had thinner pre-validation.

const long MaxBitOffset = (512L * 1024 * 1024 * 8) - 1;
if (offset < 0 || offset > MaxBitOffset)
    return BadRequest("ERR value is not an integer or out of range.");

catch (GarnetException ex) when (ex.Message == "ERR value is not an integer or out of range.") {
    // Map to a normal client error; do not treat as a server crash
    return BadRequest(ex.Message);
}

When it happens

Trigger: A bitmap operation computes a byte index from a bit offset beyond the 512 MiB-payload cap (or otherwise out of range). The bitfield commands pre-validate via TryValidateBitfieldOffset, so reaching this throw means a path that skipped/bypassed that validation, or an internal invariant violation.

Common situations: A client sends a BITFIELD/bitmap offset so large it exceeds the maximum bitmap payload; an internal caller passing an unvalidated offset.

Related errors

• ERR value is not an integer or out of range.
• BITOP DIFF operation requires at least two source bitmaps
• Elements collection cannot be empty.
• Invalid ClusterConfig payload: too short to contain a versio
• Gossip sample fraction should be in range [0,100]

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/947c6f779d6083b9. Report an issue: GitHub.