spring-projects/spring-ai · error · IllegalArgumentException

Documents list cannot be empty

Error message

Documents list cannot be empty

What it means

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.

Source

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

	protected SimpleVectorStore(SimpleVectorStoreBuilder builder) {
		super(builder);
		this.jsonMapper = JsonMapper.builder().addModules(JacksonUtils.instantiateAvailableModules()).build();
		this.filterExpressionEvaluator = new SimpleVectorStoreFilterExpressionEvaluator();
	}

	/**
	 * Creates an instance of SimpleVectorStore builder.
	 * @return the SimpleVectorStore builder.
	 */
	public static SimpleVectorStoreBuilder builder(EmbeddingModel embeddingModel) {
		return new SimpleVectorStoreBuilder(embeddingModel);
	}

	@Override
	public void doAdd(List<Document> documents) {
		Objects.requireNonNull(documents, "Documents list cannot be null");
		if (documents.isEmpty()) {
			throw new IllegalArgumentException("Documents list cannot be empty");
		}

		for (Document document : documents) {
			if (logger.isInfoEnabled()) {
				logger.info("Calling EmbeddingModel for document id = " + document.getId());
			}
			float[] embedding = this.embeddingModel.embed(document);
			SimpleVectorStoreContent storeContent = new SimpleVectorStoreContent(document.getId(),
					Objects.requireNonNullElse(document.getText(), ""), document.getMetadata(), embedding);
			this.store.put(document.getId(), storeContent);
		}
	}

	@Override
	public void doDelete(List<String> idList) {
		for (String id : idList) {
			this.store.remove(id);
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check documents.isEmpty() before calling add() and skip the call when empty.
2. Guard the batch-splitting loop so it never submits a zero-size batch.
3. If you control the producer, return an Optional<List<Document>> or null-semantics and short-circuit instead of building an empty list.

Example fix

// before
store.add(documents); // documents may be empty

// after
if (documents != null && !documents.isEmpty()) {
    store.add(documents);
}

if (documents == null || documents.isEmpty()) { return; }
store.add(documents);

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Unknown message type:
• 'spring.ai.chat.client.tool-search-advisor.tool-index-type=v
• Single parameter must be of type ElicitRequest:
• First parameter must be of type Double or double: {method.ge
• Second parameter must be of type String: {method.getName()}

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