{"record":{"id":"aacf98575cd2c421","repo":"spring-projects/spring-ai","slug":"documents-list-cannot-be-empty","errorCode":null,"errorMessage":"Documents list cannot be empty","messagePattern":"Documents list cannot be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java","lineNumber":118,"sourceCode":"\tprotected SimpleVectorStore(SimpleVectorStoreBuilder builder) {\n\t\tsuper(builder);\n\t\tthis.jsonMapper = JsonMapper.builder().addModules(JacksonUtils.instantiateAvailableModules()).build();\n\t\tthis.filterExpressionEvaluator = new SimpleVectorStoreFilterExpressionEvaluator();\n\t}\n\n\t/**\n\t * Creates an instance of SimpleVectorStore builder.\n\t * @return the SimpleVectorStore builder.\n\t */\n\tpublic static SimpleVectorStoreBuilder builder(EmbeddingModel embeddingModel) {\n\t\treturn new SimpleVectorStoreBuilder(embeddingModel);\n\t}\n\n\t@Override\n\tpublic void doAdd(List<Document> documents) {\n\t\tObjects.requireNonNull(documents, \"Documents list cannot be null\");\n\t\tif (documents.isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Documents list cannot be empty\");\n\t\t}\n\n\t\tfor (Document document : documents) {\n\t\t\tif (logger.isInfoEnabled()) {\n\t\t\t\tlogger.info(\"Calling EmbeddingModel for document id = \" + document.getId());\n\t\t\t}\n\t\t\tfloat[] embedding = this.embeddingModel.embed(document);\n\t\t\tSimpleVectorStoreContent storeContent = new SimpleVectorStoreContent(document.getId(),\n\t\t\t\t\tObjects.requireNonNullElse(document.getText(), \"\"), document.getMetadata(), embedding);\n\t\t\tthis.store.put(document.getId(), storeContent);\n\t\t}\n\t}\n\n\t@Override\n\tpublic void doDelete(List<String> idList) {\n\t\tfor (String id : idList) {\n\t\t\tthis.store.remove(id);\n\t\t}","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java#L100-L136","documentation":"SimpleVectorStore.doAdd() rejects an empty List<Document> passed to add/upsert. The store requires at least one document because the add path is meant to embed and persist real content. This is an explicit fail-fast IllegalArgumentException protecting downstream embedding calls.","triggerScenarios":"Calling SimpleVectorStore.add(List.of()) or add(Collections.emptyList()), or add(upsert) with a documents list that was filtered to zero elements before the call.","commonSituations":"Batch pipelines where a filter step (e.g. only docs matching a predicate) yields an empty list; ETL jobs processing a directory with no eligible files; loops over chunks where the last batch is empty.","solutions":["Check documents.isEmpty() before calling add() and skip the call when empty.","Guard the batch-splitting loop so it never submits a zero-size batch.","If you control the producer, return an Optional<List<Document>> or null-semantics and short-circuit instead of building an empty list."],"exampleFix":"// before\nstore.add(documents); // documents may be empty\n\n// after\nif (documents != null && !documents.isEmpty()) {\n    store.add(documents);\n}","handlingStrategy":"validation","validationCode":"if (documents == null || documents.isEmpty()) { return; }\nstore.add(documents);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never submit empty batches; guard the chunking loop boundary.","Centralize add() behind a helper that skips empty/null lists."],"tags":["vector-store","empty-list","illegal-argument"],"backgroundTag":"empty-required-field","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}