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 Int8VectorScorer.checkDimensions when the query byte-array length does not equal the indexed field's vector dimension. Int8VectorScorer handles 8-bit scalar-quantized vectors and uses native SIMD via SimdVecLibrary. The check runs in the static create() method before constructing the native scorer.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/internal/Int8VectorScorer.java:244

        @Override
        public float bulkScore(int[] nodes, float[] scores, int numNodes) throws IOException {
            if (bulkScoreWithSparse(nodes, scores, numNodes, DISTANCE_FUNCS::dotProductI8BulkSparse)) {
                float max = Float.NEGATIVE_INFINITY;
                for (int i = 0; i < numNodes; ++i) {
                    scores[i] = VectorUtil.scaleMaxInnerProductScore(scores[i]);
                    max = Math.max(max, scores[i]);
                }
                return max;
            } else {
                return super.bulkScore(nodes, scores, numNodes);
            }
        }
    }

    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

  1. Confirm the quantized query byte[] length equals the field's dimension.
  2. Run the same int8 quantization on the query embedding as at index time.
  3. Reindex if dims or quantization config changed.

Example fix

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

// after
byte[] q = quantize8bit(embed768(text));
scorer = Int8VectorScorer.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

When it happens

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

Common situations: Querying an int8-quantized dense_vector field with a byte vector of mismatched length, or mixing quantized and raw float query vectors. Also occurs after reindexing at a new dimension without updating the query pipeline.

Related errors

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