What causes "vector query dimension: {} differs from field dimension: {}" in elastic/elasticsearch?

Ensure the quantized query byte[] has exactly values.dimension() bytes.

elastic/elasticsearch · error · IllegalArgumentException

vector query dimension: {} differs from field dimension: {}

Error message

vector query dimension: {} differs from field dimension: {}

What it means

Thrown by Int7SQVectorScorer.checkDimensions when the query byte-array length does not equal the indexed field's vector dimension. Int7SQ (7-bit Scalar Quantization) stores vectors as bytes with 7-bit precision. The check fires in create() before building the scorer.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/internal/Int7SQVectorScorer.java:238

            float[] maxScore = new float[] { Float.NEGATIVE_INFINITY };
            boolean resolved = IndexInputUtils.withSliceAddresses(input, offsets, vectorPitch, numNodes, addrsScratch::get, addrs -> {
                DISTANCE_FUNCS.dotProductI7uBulkSparse(addrs, query, vectorByteSize, numNodes, MemorySegment.ofArray(scores));
                for (int i = 0; i < numNodes; ++i) {
                    float adjustedDistance = scores[i] * scoreCorrectionConstant + queryCorrection + getNodeCorrection(addrs, i);
                    scores[i] = VectorUtil.scaleMaxInnerProductScore(adjustedDistance);
                    maxScore[0] = Math.max(maxScore[0], scores[i]);
                }
            });
            if (resolved == false) {
                return super.bulkScore(nodes, scores, numNodes);
            }
            return maxScore[0];
        }
    }

    static void checkDimensions(int queryLen, int fieldLen) {
        if (queryLen != fieldLen) {
            throw new IllegalArgumentException("vector query dimension: " + queryLen + " differs from field dimension: " + fieldLen);
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

Ensure the quantized query byte[] has exactly values.dimension() bytes.
Apply the same int7 quantization to the query as was used at index time.
Reindex if the field dimension or quantization configuration changed.

Example fix

// before
byte[] q = quantize7bit(embed384(text)); // field dims:768
scorer = Int7SQVectorScorer.create(sim, values, q);

// after
byte[] q = quantize7bit(embed768(text));
scorer = Int7SQVectorScorer.create(sim, values, q);

Defensive patterns

Strategy: validation

Validate before calling

if (queryVector.length != values.dimension()) {
    throw new IllegalArgumentException("query dims " + queryVector.length + " != field dims " + values.dimension());
}

Prevention

Apply int7 quantization to the query at the same dimension as the indexed vectors.
Verify the byte[] length equals the field dimension before creating the scorer.
Reindex if quantization or dimension settings change.

When it happens

Trigger: Calling Int7SQVectorScorer.create(sim, values, queryVector) where queryVector.length (a byte[]) != values.dimension().

Common situations: Querying an int7-quantized field with a byte vector of the wrong length, or after changing quantization/dimension settings without reindexing. The query vector must be quantized to the same dimension as the stored vectors.

Related errors

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