spring-projects/spring-ai · error · IllegalArgumentException

Vectors cannot have zero norm

Error message

Vectors cannot have zero norm

What it means

EmbeddingMath.cosineSimilarity throws IllegalArgumentException 'Vectors cannot have zero norm' when either vector has zero Euclidean norm (all components zero), because cosine similarity would divide by zero. The norms here are sums of squares; a value of 0 means the vector is the zero vector.

Solutions

1. Check that embeddings are actually computed (non-zero) before similarity ranking.
2. Validate at ingestion: reject or re-embed documents whose vector norm is 0.
3. Fix the embedding pipeline so null/failed embeds never store all-zero vectors.

Example fix

// before
double s = EmbeddingMath.cosineSimilarity(queryVec, docVec); // docVec may be all zeros

// after
private boolean isZeroVector(float[] v) {
    for (float x : v) { if (x != 0f) return false; }
    return true;
}
if (!isZeroVector(docVec)) {
    double s = EmbeddingMath.cosineSimilarity(queryVec, docVec);
}

static boolean hasNonZeroNorm(float[] v) {
    if (v == null) return false;
    float sum = 0;
    for (float x : v) { sum += x * x; }
    return sum > 0f;
}
if (hasNonZeroNorm(vectorX) && hasNonZeroNorm(vectorY)) {
    double s = EmbeddingMath.cosineSimilarity(vectorX, vectorY);
}

try {
    return EmbeddingMath.cosineSimilarity(x, y);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("zero norm")) { return 0.0; }
    throw e;
}

When it happens

Trigger: Comparing a zero-filled vector, e.g. an embedding initialized but never populated, an all-zeros placeholder, or an embedding model that returned an all-zero response.

Common situations: Uninitialized float arrays used as placeholders; embeddings from failed/edge-case model calls; hand-rolled test vectors of zeros.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Vectors lengths must be equal
• Vectors must not be null

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

Appendix: source

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

		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");
			}

			return dotProduct / (Math.sqrt(normX) * Math.sqrt(normY));
		}

		public static float dotProduct(float[] vectorX, float[] vectorY) {
			if (vectorX.length != vectorY.length) {
				throw new IllegalArgumentException("Vectors lengths must be equal");
			}

			float result = 0;
			for (int i = 0; i < vectorX.length; ++i) {
				result += vectorX[i] * vectorY[i];
			}

			return result;
		}

View on GitHub (pinned to 98a7beda4f)