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 PanamaFlatVectorScorer.getRandomVectorScorer (float[] overload) when the target query vector length does not equal the vector values' dimension. PanamaFlatVectorScorer is the default Lucene Panama-based (JEP 454 Foreign Function & Memory API) flat vector scorer for float32 fields. The check fires at scorer creation before any scoring loop.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/internal/PanamaFlatVectorScorer.java:55

    @Override
    public RandomVectorScorerSupplier getRandomVectorScorerSupplier(
        VectorSimilarityFunction similarityFunction,
        KnnVectorValues vectorValues
    ) throws IOException {
        return switch (vectorValues.getEncoding()) {
            case FLOAT32 -> new FloatScoringSupplier((FloatVectorValues) vectorValues, similarityFunction);
            case BYTE -> new ByteScoringSupplier((ByteVectorValues) vectorValues, similarityFunction);
        };
    }

    @Override
    public RandomVectorScorer getRandomVectorScorer(
        VectorSimilarityFunction similarityFunction,
        KnnVectorValues vectorValues,
        float[] target
    ) throws IOException {
        if (target.length != vectorValues.dimension()) {
            throw new IllegalArgumentException(
                "vector query dimension: " + target.length + " differs from field dimension: " + vectorValues.dimension()
            );
        }
        return createScorer(similarityFunction, target, (FloatVectorValues) vectorValues);
    }

    @Override
    public RandomVectorScorer getRandomVectorScorer(
        VectorSimilarityFunction similarityFunction,
        KnnVectorValues vectorValues,
        byte[] target
    ) throws IOException {
        if (target.length != vectorValues.dimension()) {
            throw new IllegalArgumentException(
                "vector query dimension: " + target.length + " differs from field dimension: " + vectorValues.dimension()
            );
        }
        return createScorer(similarityFunction, target, (ByteVectorValues) vectorValues);

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify target.length equals the field dimension from the mapping.
2. Reindex documents if the embedding model changed.
3. Validate the query vector length before calling getRandomVectorScorer.

Example fix

// before
float[] target = embed384(text); // field dims:768
scorer = panamaScorer.getRandomVectorScorer(sim, values, target);

// after
float[] target = embed768(text);
scorer = panamaScorer.getRandomVectorScorer(sim, values, target);

if (target.length != vectorValues.dimension()) {
    throw new IllegalArgumentException("target dims " + target.length + " != field dims " + vectorValues.dimension());
}

When it happens

Trigger: Calling getRandomVectorScorer(similarityFunction, vectorValues, target) where target is a float[] and target.length != vectorValues.dimension().

Common situations: Embedding model mismatch between index and query pipelines, or querying after a dims change without reindexing. This is the standard scorer used for float32 kNN when no specialized native scorer applies.

Related errors

• vector query dimension: {} differs from field dimension: {}
• vector query dimension: {} differs from field dimension: {}
• vector query dimension: {} differs from field dimension: {}
• vector query dimension: {} differs from field dimension: {}
• invalid distance function: {}

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