spring-projects/spring-ai · error · IllegalArgumentException

<joined Weaviate error messages from GraphQL response>

Error message

<joined Weaviate error messages from GraphQL response>

What it means

doSimilaritySearch runs a raw GraphQL query against Weaviate. If the Result wrapper reports errors (transport/protocol level), the joined WeaviateErrorMessage messages are thrown as IllegalArgumentException. The query never produced usable data.

Solutions

1. Read the joined messages in the IllegalArgumentException — they contain the GraphQL error text from Weaviate.
2. Log/copy the generated graphQLQuery and run it directly against Weaviate (e.g. via GraphiQL or curl) to see the failing part.
3. Verify the configured objectClass and field names still exist in the server schema.
4. If a filter triggered it, simplify or validate the Filter.Expression against supported operators for Weaviate.

Example fix

// before
vectorStore.similaritySearch(SearchRequest.builder().query("q").topK(5).build()); // throws with joined GraphQL errors
// after
try {
    vectorStore.similaritySearch(request);
} catch (IllegalArgumentException e) {
    logger.error("Weaviate GraphQL query failed: {}", e.getMessage());
}

// sanity-check schema before searching
GET {weaviateUrl}/v1/schema and confirm the configured objectClass and field names exist

try { vectorStore.similaritySearch(req); } catch (IllegalArgumentException e) { log.error("Weaviate GraphQL failed: {}", e.getMessage()); }

When it happens

Trigger: VectorStore.similaritySearch(SearchRequest) when the raw GraphQL .run() returns hasErrors() — invalid GraphQL syntax after filter substitution, unknown class/field names, authentication failure, or server error.

Common situations: Filter expressions translating to GraphQL where clauses the server rejects; querying a renamed/deleted class; wrong field names in options (contentFieldName) after schema change; expired Weaviate Cloud credentials.

Related errors

• <joined GraphQL error messages>
• Failed to delete documents by filter
• Failed to add documents because:
• Failed to delete documents because:
• Failed to serialize the Document metadata:

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

Appendix: source

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

			.fields(Fields.builder().fields(this.weaviateSimilaritySearchFields).build());

		String graphQLQuery = queryBuilder.build().buildQuery();

		if (request.hasFilterExpression()) {
			Assert.state(request.getFilterExpression() != null, "filter expression must not be null");
			// replace the empty 'where:{}' placeholder with real filter.
			String filter = this.filterExpressionConverter.convertExpression(request.getFilterExpression());
			graphQLQuery = graphQLQuery.replace("where:{}", String.format("where:{%s}", filter));
		}
		else {
			// remove the empty 'where:{}' placeholder.
			graphQLQuery = graphQLQuery.replace("where:{}", "");
		}

		Result<GraphQLResponse> result = this.weaviateClient.graphQL().raw().withQuery(graphQLQuery).run();

		if (result.hasErrors()) {
			throw new IllegalArgumentException(result.getError()
				.getMessages()
				.stream()
				.map(WeaviateErrorMessage::getMessage)
				.collect(Collectors.joining(System.lineSeparator())));
		}

		GraphQLError[] errors = result.getResult().getErrors();
		if (errors != null && errors.length > 0) {
			throw new IllegalArgumentException(Arrays.stream(errors)
				.map(GraphQLError::getMessage)
				.collect(Collectors.joining(System.lineSeparator())));
		}

		@SuppressWarnings("unchecked")
		Optional<Map.Entry<String, Map<?, ?>>> resGetPart = ((Map<String, Map<?, ?>>) result.getResult().getData())
			.entrySet()
			.stream()
			.findFirst();

View on GitHub (pinned to 98a7beda4f)