{"record":{"id":"acfd410f84877ce4","repo":"spring-projects/spring-ai","slug":"failed-to-add-documents-because","errorCode":null,"errorMessage":"Failed to add documents because: \n","messagePattern":"Failed to add documents because: \n","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateVectorStore.java","lineNumber":220,"sourceCode":"\t\tList<WeaviateObject> weaviateObjects = documents.stream()\n\t\t\t.map(document -> toWeaviateObject(document, documents, embeddings))\n\t\t\t.toList();\n\n\t\tResult<ObjectGetResponse[]> response = this.weaviateClient.batch()\n\t\t\t.objectsBatcher()\n\t\t\t.withObjects(weaviateObjects.toArray(new WeaviateObject[0]))\n\t\t\t.withConsistencyLevel(this.consistencyLevel.name())\n\t\t\t.run();\n\n\t\tList<String> errorMessages = new ArrayList<>();\n\n\t\tif (response.hasErrors()) {\n\t\t\terrorMessages.add(response.getError()\n\t\t\t\t.getMessages()\n\t\t\t\t.stream()\n\t\t\t\t.map(WeaviateErrorMessage::getMessage)\n\t\t\t\t.collect(Collectors.joining(System.lineSeparator())));\n\t\t\tthrow new RuntimeException(\"Failed to add documents because: \\n\" + errorMessages);\n\t\t}\n\n\t\tif (response.getResult() != null) {\n\t\t\tfor (var r : response.getResult()) {\n\t\t\t\tif (r.getResult() != null && r.getResult().getErrors() != null) {\n\t\t\t\t\tvar error = r.getResult().getErrors();\n\t\t\t\t\terrorMessages.add(error.getError()\n\t\t\t\t\t\t.stream()\n\t\t\t\t\t\t.map(ObjectsGetResponseAO2Result.ErrorItem::getMessage)\n\t\t\t\t\t\t.collect(Collectors.joining(System.lineSeparator())));\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (!CollectionUtils.isEmpty(errorMessages)) {\n\t\t\tthrow new RuntimeException(\"Failed to add documents because: \\n\" + errorMessages);\n\t\t}\n\t}","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateVectorStore.java#L202-L238","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the Weaviate client connectivity (curl the /v1/.well-known/ready endpoint) and fix the URL/ports in the client configuration.","Check API key configuration (Weaviate Cloud requires X-Weaviate-Api-Key headers configured on the client).","Inspect the joined error messages appended after 'because: \\n' — the RuntimeException message contains the actual Weaviate error details.","Ensure the target class/schema exists in Weaviate and matches this.options (objectClass, field names)."],"exampleFix":"// before\nvectorStore.add(documents); // throws with confusing 'Failed to add documents because: \\n[...]'\n// after\ntry {\n    vectorStore.add(documents);\n} catch (RuntimeException e) {\n    logger.error(\"Weaviate batch add failed: {}\", e.getMessage(), e); // message includes joined Weaviate errors\n}","handlingStrategy":"try-catch","validationCode":"// before calling add\nboolean ready = HttpClient.newHttpClient().send(\n    HttpRequest.newBuilder(URI.create(weaviateUrl + \"/v1/.well-known/ready\")).build(),\n    HttpResponse.BodyHandlers.ofString()).statusCode() == 200;","typeGuard":null,"tryCatchPattern":"try { vectorStore.add(docs); } catch (RuntimeException e) { log.error(\"Weaviate batch add failed: {}\", e.getMessage(), e); throw e; }","preventionTips":["Health-check the Weaviate /v1/.well-known/ready endpoint at startup","Verify API key and URL configuration before first write","Log the joined error message body of the exception — it carries the real cause"],"tags":["weaviate","vector-store","batch-add","network"],"backgroundTag":"api-error-response","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}