{"record":{"id":"c3e1fa12f72ac44d","repo":"spring-projects/spring-ai","slug":"unsupported-similarity-similarity","errorCode":null,"errorMessage":"Unsupported similarity: {similarity}","messagePattern":"Unsupported similarity: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java","lineNumber":352,"sourceCode":"\t\t\t\t.create(cr -> cr.index(this.options.getIndexName())\n\t\t\t\t\t.mappings(\n\t\t\t\t\t\t\tmap -> map.properties(this.options.getEmbeddingFieldName(),\n\t\t\t\t\t\t\t\t\tp -> p.denseVector(dv -> dv\n\t\t\t\t\t\t\t\t\t\t.similarity(parseSimilarity(this.options.getSimilarity().toString()))\n\t\t\t\t\t\t\t\t\t\t.dims(this.options.getDimensions())))));\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\t}\n\n\tprivate DenseVectorSimilarity parseSimilarity(String similarity) {\n\t\tfor (DenseVectorSimilarity sim : DenseVectorSimilarity.values()) {\n\t\t\tif (sim.jsonValue().equalsIgnoreCase(similarity)) {\n\t\t\t\treturn sim;\n\t\t\t}\n\t\t}\n\t\tthrow new IllegalArgumentException(\"Unsupported similarity: \" + similarity);\n\t}\n\n\t@Override\n\tpublic void afterPropertiesSet() {\n\t\t// For the index to be present, either it must be pre-created or set the\n\t\t// initializeSchema to true.\n\t\tif (indexExists()) {\n\t\t\treturn;\n\t\t}\n\t\tif (!this.initializeSchema) {\n\t\t\tthrow new IllegalArgumentException(\"Index not found\");\n\t\t}\n\t\tcreateIndexMapping();\n\t}\n\n\t@Override\n\tpublic VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {\n\t\treturn VectorStoreObservationContext.builder(VectorStoreProvider.ELASTICSEARCH.value(), operationName)","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java#L334-L370","documentation":"ElasticsearchVectorStore.parseSimilarity converts the configured similarity string into a DenseVectorSimilarity enum by matching Elasticsearch's jsonValue(); if no enum value matches (case-insensitively) it throws IllegalArgumentException(\"Unsupported similarity: ...\"). It guards index creation against invalid dense_vector similarity settings.","triggerScenarios":"Calling createIndexMapping (via afterPropertiesSet with initializeSchema=true) when ElasticsearchVectorStoreOptions.getSimilarity() returns a string other than cosine, l2_norm, dot_product (or max_inner_product depending on version).","commonSituations":"Typo or wrong casing in similarity config property, copying a similarity name from another vector store (e.g. 'euclidean' or 'cosine_distance') that Elasticsearch does not define, older/newer Elasticsearch versions with different enum values.","solutions":["Set similarity to a valid Elasticsearch dense_vector value: cosine, l2_norm, or dot_product","Check ElasticsearchVectorStoreOptions.setSimilarity(...) for the exact accepted strings","Align the value with your Elasticsearch version's supported dense_vector similarity options"],"exampleFix":"// before\noptions.setSimilarity(\"euclidean\");\n// after\noptions.setSimilarity(\"l2_norm\");","handlingStrategy":"validation","validationCode":"Set<String> VALID = Set.of(\"cosine\", \"l2_norm\", \"dot_product\");\nif (!VALID.contains(options.getSimilarity().toLowerCase())) throw new IllegalArgumentException(\"Invalid similarity: \" + options.getSimilarity());","typeGuard":null,"tryCatchPattern":"try {\n    new ElasticsearchVectorStore(client, options, embeddingModel);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Unsupported similarity\")) {\n        throw new IllegalStateException(\"Set similarity to cosine, l2_norm, or dot_product\", e);\n    }\n    throw e;\n}","preventionTips":["Use only similarity values defined by Elasticsearch dense_vector","Centralize similarity configuration in one validated property","Check the Elasticsearch version docs when upgrading"],"tags":["elasticsearch","configuration","similarity","enum","vector-store"],"backgroundTag":"invalid-enum-value","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}