spring-projects/spring-ai · error · IllegalArgumentException

Unsupported similarity: {similarity}

Error message

Unsupported similarity: {similarity}

What it means

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.

Source

Thrown at vector-stores/spring-ai-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java:352

				.create(cr -> cr.index(this.options.getIndexName())
					.mappings(
							map -> map.properties(this.options.getEmbeddingFieldName(),
									p -> p.denseVector(dv -> dv
										.similarity(parseSimilarity(this.options.getSimilarity().toString()))
										.dims(this.options.getDimensions())))));
		}
		catch (IOException e) {
			throw new RuntimeException(e);
		}
	}

	private DenseVectorSimilarity parseSimilarity(String similarity) {
		for (DenseVectorSimilarity sim : DenseVectorSimilarity.values()) {
			if (sim.jsonValue().equalsIgnoreCase(similarity)) {
				return sim;
			}
		}
		throw new IllegalArgumentException("Unsupported similarity: " + similarity);
	}

	@Override
	public void afterPropertiesSet() {
		// For the index to be present, either it must be pre-created or set the
		// initializeSchema to true.
		if (indexExists()) {
			return;
		}
		if (!this.initializeSchema) {
			throw new IllegalArgumentException("Index not found");
		}
		createIndexMapping();
	}

	@Override
	public VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {
		return VectorStoreObservationContext.builder(VectorStoreProvider.ELASTICSEARCH.value(), operationName)

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set similarity to a valid Elasticsearch dense_vector value: cosine, l2_norm, or dot_product
2. Check ElasticsearchVectorStoreOptions.setSimilarity(...) for the exact accepted strings
3. Align the value with your Elasticsearch version's supported dense_vector similarity options

Example fix

// before
options.setSimilarity("euclidean");
// after
options.setSimilarity("l2_norm");

Set<String> VALID = Set.of("cosine", "l2_norm", "dot_product");
if (!VALID.contains(options.getSimilarity().toLowerCase())) throw new IllegalArgumentException("Invalid similarity: " + options.getSimilarity());

try {
    new ElasticsearchVectorStore(client, options, embeddingModel);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported similarity")) {
        throw new IllegalStateException("Set similarity to cosine, l2_norm, or dot_product", e);
    }
    throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Index not found
• Unknown model provider:
• Not supported expression type: {expressionType}
• Delete operation failed
• Failed to delete documents by filter

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/c3e1fa12f72ac44d. Report an issue: GitHub.