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 Float32VectorScorer.checkDimensions when the query vector length does not equal the indexed field's vector dimension. This scorer handles standard float32 dense vectors. The check fires in the static create() method at scorer-construction time.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/internal/Float32VectorScorer.java:231

                numNodes,
                addrsScratch::get,
                addrs -> DISTANCE_FUNCS.dotProductF32BulkSparse(addrs, query, dimensions, numNodes, MemorySegment.ofArray(scores))
            );
            if (resolved) {
                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;
            }
            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. Verify the field mapping dims (GET index/_mapping) and ensure the query vector has exactly that many elements.
  2. Reindex documents if the embedding model or dimension changed.
  3. Pre-validate the query vector length client-side before issuing the search.

Example fix

// before
float[] query = embed384(text); // field is dims:768
scorer = Float32VectorScorer.create(sim, values, query);

// after
float[] query = embed768(text); // matches field dims
scorer = Float32VectorScorer.create(sim, values, query);
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 Float32VectorScorer.create(sim, values, queryVector) where queryVector.length != values.dimension().

Common situations: Querying a dense_vector field with an embedding from a different model/dimension, or after a mapping dims change without reindexing. The most common kNN dimension-mismatch scenario for float32 fields.

Related errors

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