elastic/elasticsearch · error · IllegalArgumentException

invalid distance function: {}

Error message

invalid distance function: {}

What it means

Thrown by ES92GpuHnswVectorsWriter.distFuncToOrd() when the provided VectorSimilarityFunction is not found in Lucene99HnswVectorsReader.SIMILARITY_FUNCTIONS. This list contains the supported similarity functions for the Lucene99 HNSW format: EUCLIDEAN, DOT_PRODUCT, COSINE, and MAXIMUM_INNER_PRODUCT. The function is called during writeMeta() to serialize the similarity function ordinal.

Source

Thrown at libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java:873

        }
    }

    @Override
    public void close() throws IOException {
        if (isFlatWriterClosed()) {
            IOUtils.close(meta, vectorIndex, flatVectorsReader);
        } else {
            IOUtils.close(meta, vectorIndex, flatVectorWriter, flatVectorsReader);
        }
    }

    static int distFuncToOrd(VectorSimilarityFunction func) {
        for (int i = 0; i < SIMILARITY_FUNCTIONS.size(); i++) {
            if (SIMILARITY_FUNCTIONS.get(i).equals(func)) {
                return (byte) i;
            }
        }
        throw new IllegalArgumentException("invalid distance function: " + func);
    }

    private static class FieldWriter extends KnnFieldVectorsWriter<float[]> {
        private static final long SHALLOW_SIZE = RamUsageEstimator.shallowSizeOfInstance(FieldWriter.class);

        private final FieldInfo fieldInfo;
        private int lastDocID = -1;
        private final FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter;

        FieldWriter(FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter, FieldInfo fieldInfo) {
            this.fieldInfo = fieldInfo;
            this.flatFieldVectorsWriter = Objects.requireNonNull(flatFieldVectorsWriter);
        }

        @Override
        public void addValue(int docID, float[] vectorValue) throws IOException {
            if (docID == lastDocID) {
                throw new IllegalArgumentException(

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify that the dense_vector mapping uses one of the supported similarity functions: cosine, dot_product, l2_norm, or max_inner_product.
2. If a Lucene upgrade introduced a new VectorSimilarityFunction, update SIMILARITY_FUNCTIONS in Lucene99HnswVectorsReader or add handling for the new function.
3. Use a supported similarity function in the index mapping.

Example fix

// before — using an unsupported similarity
// mapping: { "similarity": "some_new_function" }

// after — use a supported similarity
// mapping: { "similarity": "cosine" }

Set<VectorSimilarityFunction> supported = Set.of(
    VectorSimilarityFunction.EUCLIDEAN,
    VectorSimilarityFunction.DOT_PRODUCT,
    VectorSimilarityFunction.COSINE,
    VectorSimilarityFunction.MAXIMUM_INNER_PRODUCT
);
if (!supported.contains(similarityFunction)) {
    throw new IllegalArgumentException("Unsupported similarity function: " + similarityFunction);
}

static boolean isSupportedSimilarity(VectorSimilarityFunction func) {
    return func == VectorSimilarityFunction.EUCLIDEAN
        || func == VectorSimilarityFunction.DOT_PRODUCT
        || func == VectorSimilarityFunction.COSINE
        || func == VectorSimilarityFunction.MAXIMUM_INNER_PRODUCT;
}

When it happens

Trigger: Passing a VectorSimilarityFunction that is not in the SIMILARITY_FUNCTIONS list. In standard Lucene, there are only four VectorSimilarityFunction enum values and all are supported. This would only fire if a new VectorSimilarityFunction enum value were added to Lucene but not yet registered in SIMILARITY_FUNCTIONS, or if a custom/unknown similarity function somehow reaches the GPU writer.

Common situations: Lucene version upgrade adding a new VectorSimilarityFunction not yet handled by the GPU codec; custom Lucene fork with additional similarity functions; extremely unlikely in normal Elasticsearch operation.

Related errors

• segment of size [{}] too small for expected {} float vectors
• negative number of vectors: {}
• negative vector dims: {}
• maxConn must be positive and less than or equal to 512; maxC
• beamWidth must be positive and less than or equal to 3200; b

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