spring-projects/spring-ai · error · RuntimeException

Failed to add documents because:

Error message

Failed to add documents because: 

What it means

WeaviateVectorStore.doAdd() batches documents to Weaviate via the batch client. If the batch response object itself carries top-level errors, it joins the WeaviateErrorMessage messages and throws an unchecked RuntimeException. This means the HTTP batch request failed at the transport/request level rather than per-object.

Solutions

1. Verify the Weaviate client connectivity (curl the /v1/.well-known/ready endpoint) and fix the URL/ports in the client configuration.
2. Check API key configuration (Weaviate Cloud requires X-Weaviate-Api-Key headers configured on the client).
3. Inspect the joined error messages appended after 'because: \n' — the RuntimeException message contains the actual Weaviate error details.
4. Ensure the target class/schema exists in Weaviate and matches this.options (objectClass, field names).

Example fix

// before
vectorStore.add(documents); // throws with confusing 'Failed to add documents because: \n[...]'
// after
try {
    vectorStore.add(documents);
} catch (RuntimeException e) {
    logger.error("Weaviate batch add failed: {}", e.getMessage(), e); // message includes joined Weaviate errors
}

// before calling add
boolean ready = HttpClient.newHttpClient().send(
    HttpRequest.newBuilder(URI.create(weaviateUrl + "/v1/.well-known/ready")).build(),
    HttpResponse.BodyHandlers.ofString()).statusCode() == 200;

try { vectorStore.add(docs); } catch (RuntimeException e) { log.error("Weaviate batch add failed: {}", e.getMessage(), e); throw e; }

When it happens

Trigger: Calling VectorStore.add(List<Document>) (which delegates to doAdd) when the Weaviate batch API returns Result.hasErrors() == true — e.g. unreachable server, invalid API key, malformed batch request, or gRPC/HTTP transport failure.

Common situations: Weaviate not running or wrong URL in WeaviateVectorStore.builder().withWeaviateClient(...); missing/incorrect API key for Weaviate Cloud; network/firewall blocking the batch endpoint; schema/class deleted while the store was in use.

Related errors

• Failed to delete documents because:
• Failed to delete documents by filter
• Got an unexpected error
• Not allowed filter identifier name: . Consider adding it to…
• Not supported expression type:

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

Appendix: source

Thrown at vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateVectorStore.java:220

		List<WeaviateObject> weaviateObjects = documents.stream()
			.map(document -> toWeaviateObject(document, documents, embeddings))
			.toList();

		Result<ObjectGetResponse[]> response = this.weaviateClient.batch()
			.objectsBatcher()
			.withObjects(weaviateObjects.toArray(new WeaviateObject[0]))
			.withConsistencyLevel(this.consistencyLevel.name())
			.run();

		List<String> errorMessages = new ArrayList<>();

		if (response.hasErrors()) {
			errorMessages.add(response.getError()
				.getMessages()
				.stream()
				.map(WeaviateErrorMessage::getMessage)
				.collect(Collectors.joining(System.lineSeparator())));
			throw new RuntimeException("Failed to add documents because: \n" + errorMessages);
		}

		if (response.getResult() != null) {
			for (var r : response.getResult()) {
				if (r.getResult() != null && r.getResult().getErrors() != null) {
					var error = r.getResult().getErrors();
					errorMessages.add(error.getError()
						.stream()
						.map(ObjectsGetResponseAO2Result.ErrorItem::getMessage)
						.collect(Collectors.joining(System.lineSeparator())));
				}
			}
		}

		if (!CollectionUtils.isEmpty(errorMessages)) {
			throw new RuntimeException("Failed to add documents because: \n" + errorMessages);
		}
	}

View on GitHub (pinned to 98a7beda4f)