{"record":{"id":"6757862f4f453dbc","repo":"elastic/elasticsearch","slug":"invalid-distance-function","errorCode":null,"errorMessage":"invalid distance function: {}","messagePattern":"invalid distance function: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java","lineNumber":873,"sourceCode":"        }\n    }\n\n    @Override\n    public void close() throws IOException {\n        if (isFlatWriterClosed()) {\n            IOUtils.close(meta, vectorIndex, flatVectorsReader);\n        } else {\n            IOUtils.close(meta, vectorIndex, flatVectorWriter, flatVectorsReader);\n        }\n    }\n\n    static int distFuncToOrd(VectorSimilarityFunction func) {\n        for (int i = 0; i < SIMILARITY_FUNCTIONS.size(); i++) {\n            if (SIMILARITY_FUNCTIONS.get(i).equals(func)) {\n                return (byte) i;\n            }\n        }\n        throw new IllegalArgumentException(\"invalid distance function: \" + func);\n    }\n\n    private static class FieldWriter extends KnnFieldVectorsWriter<float[]> {\n        private static final long SHALLOW_SIZE = RamUsageEstimator.shallowSizeOfInstance(FieldWriter.class);\n\n        private final FieldInfo fieldInfo;\n        private int lastDocID = -1;\n        private final FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter;\n\n        FieldWriter(FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter, FieldInfo fieldInfo) {\n            this.fieldInfo = fieldInfo;\n            this.flatFieldVectorsWriter = Objects.requireNonNull(flatFieldVectorsWriter);\n        }\n\n        @Override\n        public void addValue(int docID, float[] vectorValue) throws IOException {\n            if (docID == lastDocID) {\n                throw new IllegalArgumentException(","sourceCodeStart":855,"sourceCodeEnd":891,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java#L855-L891","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify that the dense_vector mapping uses one of the supported similarity functions: cosine, dot_product, l2_norm, or max_inner_product.","If a Lucene upgrade introduced a new VectorSimilarityFunction, update SIMILARITY_FUNCTIONS in Lucene99HnswVectorsReader or add handling for the new function.","Use a supported similarity function in the index mapping."],"exampleFix":"// before — using an unsupported similarity\n// mapping: { \"similarity\": \"some_new_function\" }\n\n// after — use a supported similarity\n// mapping: { \"similarity\": \"cosine\" }","handlingStrategy":"validation","validationCode":"Set<VectorSimilarityFunction> supported = Set.of(\n    VectorSimilarityFunction.EUCLIDEAN,\n    VectorSimilarityFunction.DOT_PRODUCT,\n    VectorSimilarityFunction.COSINE,\n    VectorSimilarityFunction.MAXIMUM_INNER_PRODUCT\n);\nif (!supported.contains(similarityFunction)) {\n    throw new IllegalArgumentException(\"Unsupported similarity function: \" + similarityFunction);\n}","typeGuard":"static boolean isSupportedSimilarity(VectorSimilarityFunction func) {\n    return func == VectorSimilarityFunction.EUCLIDEAN\n        || func == VectorSimilarityFunction.DOT_PRODUCT\n        || func == VectorSimilarityFunction.COSINE\n        || func == VectorSimilarityFunction.MAXIMUM_INNER_PRODUCT;\n}","tryCatchPattern":null,"preventionTips":["Use only the four standard Lucene VectorSimilarityFunction values in dense_vector mappings.","When upgrading Lucene, check if new VectorSimilarityFunction enum values were added and update the codec if needed."],"tags":["gpu-codec","vector-search","validation","similarity-function","lucene"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}