elastic/elasticsearch · error · IllegalArgumentException

distancesOffset must be between have length 0 and distances.

Error message

distancesOffset must be between have length 0 and distances.length - 4

What it means

Thrown by ESVectorUtil.squareDistanceBulk (distancesOffset overload) when distancesOffset is negative or larger than distances.length - 4. The method writes four consecutive results starting at distancesOffset, so the offset must leave room for all four. Note: the message text contains a known typo ('between have length 0').

Source

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

     * @throws IllegalArgumentException if the dimensions of the vectors do not match or if the distances array does not have length 4
     */
    public static void squareDistanceBulk(
        float[] q,
        float[] v0,
        float[] v1,
        float[] v2,
        float[] v3,
        int distancesOffset,
        float[] distances
    ) {
        if (q.length != v0.length || q.length != v1.length || q.length != v2.length || q.length != v3.length) {
            throw new IllegalArgumentException("vector dimensions incompatible");
        }
        if (distances.length < 4) {
            throw new IllegalArgumentException("distances array must have length >= 4, but was: " + distances.length);
        }
        if (distancesOffset < 0 || distancesOffset > distances.length - 4) {
            throw new IllegalArgumentException("distancesOffset must be between have length 0 and distances.length - 4");
        }
        IMPL.squareDistanceBulk(q, 0, v0, v1, v2, v3, distancesOffset, distances, q.length);
    }

    /**
     * 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. Ensure 0 <= distancesOffset and distancesOffset + 4 <= distances.length before calling.
  2. If packing results, advance the offset by exactly 4 per batch and stop before the end of the buffer.
  3. If only one batch is needed, pass distancesOffset = 0 and a length-4 array.

Example fix

// before
ESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, offset, dists);

// after
if (offset < 0 || offset + 4 > dists.length) {
    throw new IllegalArgumentException("bad offset " + offset + " for dists len " + dists.length);
}
ESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, offset, dists);
Defensive patterns

Strategy: validation

Validate before calling

if (distancesOffset < 0 || distancesOffset > distances.length - 4) {
    throw new IllegalArgumentException("offset " + distancesOffset + " out of range for len " + distances.length);
}

Prevention

When it happens

Trigger: Calling squareDistanceBulk with distancesOffset < 0, or distancesOffset > distances.length - 4. For example, offset 2 into a length-4 array triggers it because 2 > 4 - 4 = 0.

Common situations: A caller packs multiple bulk results into one large distances array and computes the offset incorrectly (off-by-one, or not accounting for the fixed 4-result stride). Also occurs when distancesOffset is derived from a node ordinal without clamping.

Related errors

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