spring-projects/spring-ai · warning · UnsupportedOperationException

This is a utility class and cannot be instantiated

Error message

This is a utility class and cannot be instantiated

What it means

SimpleVectorStore.EmbeddingMath is a pure static utility class whose constructor deliberately throws UnsupportedOperationException. It exists only to host static math helpers (cosineSimilarity, dotProduct, norm) and is never meant to be instantiated.

Source

Thrown at spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java:267

	}

	private float[] getUserQueryEmbedding(String query) {
		return this.embeddingModel.embed(query);
	}

	@Override
	public VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {

		return VectorStoreObservationContext.builder(VectorStoreProvider.SIMPLE.value(), operationName)
			.dimensions(this.embeddingModel.dimensions())
			.collectionName("in-memory-map")
			.similarityMetric(VectorStoreSimilarityMetric.COSINE.value());
	}

	public static final class EmbeddingMath {

		private EmbeddingMath() {
			throw new UnsupportedOperationException("This is a utility class and cannot be instantiated");
		}

		public static double cosineSimilarity(float[] vectorX, float[] vectorY) {
			if (vectorX == null || vectorY == null) {
				throw new RuntimeException("Vectors must not be null");
			}
			if (vectorX.length != vectorY.length) {
				throw new IllegalArgumentException("Vectors lengths must be equal");
			}

			float dotProduct = dotProduct(vectorX, vectorY);
			float normX = norm(vectorX);
			float normY = norm(vectorY);

			if (normX == 0 || normY == 0) {
				throw new IllegalArgumentException("Vectors cannot have zero norm");
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Do not instantiate it; call static methods directly: SimpleVectorStore.EmbeddingMath.cosineSimilarity(x, y).
2. Remove any code, config, or test that tries to construct the class.

Example fix

// before
SimpleVectorStore.EmbeddingMath math = new SimpleVectorStore.EmbeddingMath();
double s = math.cosineSimilarity(x, y);

// after
double s = SimpleVectorStore.EmbeddingMath.cosineSimilarity(x, y);

static boolean isEmbeddingMathInstance(Object o) {
    return o instanceof SimpleVectorStore.EmbeddingMath; // never construct it
}

double s = SimpleVectorStore.EmbeddingMath.cosineSimilarity(x, y); // static call only

When it happens

Trigger: Calling new SimpleVectorStore.EmbeddingMath() or using reflection/instantiation utilities (e.g. Jackson, Spring bean creation, tests) against the nested class.

Common situations: IDE auto-complete accidents; framework scanning that instantiates nested classes; writing tests that accidentally construct the utility.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• This is a utility class and cannot be instantiated
• This is a utility class and cannot be instantiated
• instantiation failed
• Roots not supported by the client:
• Currently only methods with a single ElicitRequest parameter

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