elastic/elasticsearch · error · IllegalArgumentException

bit must be between 1 and 8, but was: {}

Error message

bit must be between 1 and 8, but was: {}

What it means

Thrown by quantizeVectorWithIntervals when the bit parameter is outside the inclusive range [1, 8]. OSQ supports 1 to 8 bits per quantized value because the destination is int-backed and the SIMD kernel operates on byte-wide lanes. The guard rejects zero, negative, or >8 bit depths before they corrupt the quantization grid.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java:685

    }

    /**
     * Optimized-scalar quantization of the provided vector to the provided destination array.
     *
     * @param vector the vector to quantize
     * @param destination the array to store the result
     * @param lowInterval the minimum value, lower values in the original array will be replaced by this value
     * @param upperInterval the maximum value, bigger values in the original array will be replaced by this value
     * @param bit the number of bits to use for quantization, must be between 1 and 8
     *
     * @return return the sum of all the elements of the resulting quantized vector.
     */
    public static int quantizeVectorWithIntervals(float[] vector, int[] destination, float lowInterval, float upperInterval, byte bit) {
        if (vector.length > destination.length) {
            throw new IllegalArgumentException("vector dimensions differ: " + vector.length + "!=" + destination.length);
        }
        if (bit <= 0 || bit > Byte.SIZE) {
            throw new IllegalArgumentException("bit must be between 1 and 8, but was: " + bit);
        }
        return IMPL.quantizeVectorWithIntervals(vector, destination, lowInterval, upperInterval, bit);
    }

    /**
     * Bulk computation of square distances between a query vector and four vectors.Result is stored in the provided distances array.
     *
     * @param q the query vector
     * @param v0 the first vector
     * @param v1 the second vector
     * @param v2 the third vector
     * @param v3 the fourth vector
     * @param distancesOffset offset to the location in the distances array where we want to store the 4 results,
     *                        we require distancesOffset to be between 0 and distances.length - 4
     * @param distances an array to store the computed square distances, must have length >= 4
     *
     * @throws IllegalArgumentException if the dimensions of the vectors do not match or if the distances array does not have length 4
     */

View on GitHub (pinned to db6a809a66)

Solutions

1. Validate that bit is between 1 and 8 inclusive before calling; clamp or reject at the configuration layer.
2. Check the OSQ bits setting in the index mapping / index settings and correct it to a value in [1, 8].
3. If bit arrives as a signed byte from a wider field, mask and range-check it before passing to this API.

Example fix

// before
int sum = ESVectorUtil.quantizeVectorWithIntervals(vector, destination, low, upper, bits);
// after
if (bits <= 0 || bits > Byte.SIZE) {
    throw new IllegalArgumentException("OSQ bits must be 1..8, got " + bits);
}
int sum = ESVectorUtil.quantizeVectorWithIntervals(vector, destination, low, upper, bits);

if (bit <= 0 || bit > Byte.SIZE) {
    throw new IllegalArgumentException("OSQ bits must be 1..8, got " + bit);
}
int sum = ESVectorUtil.quantizeVectorWithIntervals(vector, destination, lowInterval, upperInterval, bit);

static boolean isValidOsqBits(byte bit) {
    return bit > 0 && bit <= Byte.SIZE;
}

When it happens

Trigger: Calling ESVectorUtil.quantizeVectorWithIntervals(float[], int[], float, float, byte bit) with bit <= 0 or bit > 8. Happens when the OSQ configuration is read from a mapping or setting that allows an out-of-range bits value, or when a default byte (signed) carrying -1 leaks into the bit parameter.

Common situations: OSQ bits setting misconfigured to 0 or 9+; signed byte overflow where a value like 0xFF (-1) is passed as bit; index setting inherited from a template with an invalid bits value; upgrade that introduced a new default bits value not yet validated at the mapping layer.

Related errors

• Unsupported query/index bits combination: {}/{}
• Can't create extra config file from {} for {} as it does not
• Can't create extra config file for
• extra jar file {} doesn't appear to be a JAR
• Not a valid module {} for {}

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/5f6d659bbdb86823. Report an issue: GitHub.