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 BFloat16VectorScorer.checkDimensions when the query vector length does not equal the indexed field's vector dimension. This scorer handles bfloat16 (brain float) vectors. The check is invoked from the static create() method before constructing a scorer, so it fires at scorer-creation time, not per-document.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/internal/BFloat16VectorScorer.java:233

                numNodes,
                addrsScratch::get,
                addrs -> DISTANCE_FUNCS.dotProductDBF16QF32BulkSparse(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. Match the query vector dimension to the field's configured dims (check the index mapping: PUT index/_mapping or GET index/_mapping).
  2. If the embedding model changed, reindex all documents with the new model before querying.
  3. Validate the query vector length against the mapping before sending the kNN query.

Example fix

// before
GET my-index/_search
{ "knn": { "query_vector": [0.1, 0.2, ... /* 384 dims */], ... } }

// after — field is mapped as dims:768, so supply a 768-dim vector
GET my-index/_search
{ "knn": { "query_vector": [/* 768 dims from the same model */], ... } }
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 BFloat16VectorScorer.create(sim, values, queryVector) where queryVector.length != values.dimension(). The create() method is called by the scorer-provider pipeline when resolving a kNN query against bfloat16 fields.

Common situations: Indexing a dense_vector field at one dimension (e.g. dims: 768) then querying with a vector of a different size (e.g. 384). Also occurs after changing the mapping dims without reindexing, or passing a model embedding from a different model than the one used for indexing.

Related errors

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