spring-projects/spring-ai · error · IllegalArgumentException

Only text documents are supported for now. One of the…

Error message

Only text documents are supported for now. One of the documents contains non-text content.

What it means

AbstractObservationVectorStore.add validates documents before embedding/upserting: multimodal (non-text) Documents are not supported by vector stores. validateNonTextDocuments throws IllegalArgumentException if any non-null document reports isText() == false, because current embedding and storage paths handle text content only.

Solutions

1. Only pass text-content Documents to vectorStore.add(); convert media to text (transcribe/OCR) first
2. Filter the list before calling add: documents.stream().filter(Document::isText).toList()
3. Route non-text documents to a multimodal-capable store or handle them in a separate pipeline
4. Check Document.isText() when building ingestion batches and log/skip offending documents

Example fix

// before
vectorStore.add(documents);
// after
vectorStore.add(documents.stream().filter(Document::isText).toList());

List<Document> textDocs = documents == null ? List.of() : documents.stream().filter(d -> d != null && d.isText()).toList();

boolean isAddable(Document d) { return d != null && d.isText(); }

try { vectorStore.add(docs); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("non-text")) { /* filter and retry */ } else throw e; }

When it happens

Trigger: Calling vectorStore.add(List.of(doc)) or add(List.of(doc), options) with a Document built from media/other modality (Document.builder().media(...)) instead of text content.

Common situations: Multimodal RAG pipelines feeding image/audio Documents into a text-only vector store; upgrading to a Spring AI version where add() started validating document modality; generic ingestion code that mixes modalities.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Anthropic Citations API requires all documents to have…
• At least one client Id must be specified
• Bad Request
• Bean must not be null
• Bean must not be null

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

Appendix: source

Thrown at spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/observation/AbstractObservationVectorStore.java:93

	public void add(List<Document> documents) {
		validateNonTextDocuments(documents);
		VectorStoreObservationContext observationContext = this
			.createObservationContextBuilder(VectorStoreObservationContext.Operation.ADD.value())
			.build();

		VectorStoreObservationDocumentation.AI_VECTOR_STORE
			.observation(this.customObservationConvention, DEFAULT_OBSERVATION_CONVENTION, () -> observationContext,
					this.observationRegistry)
			.observe(() -> this.doAdd(documents));
	}

	private void validateNonTextDocuments(List<Document> documents) {
		if (documents == null) {
			return;
		}
		for (Document document : documents) {
			if (document != null && !document.isText()) {
				throw new IllegalArgumentException(
						"Only text documents are supported for now. One of the documents contains non-text content.");
			}
		}
	}

	@Override
	public void delete(List<String> deleteDocIds) {

		VectorStoreObservationContext observationContext = this
			.createObservationContextBuilder(VectorStoreObservationContext.Operation.DELETE.value())
			.build();

		VectorStoreObservationDocumentation.AI_VECTOR_STORE
			.observation(this.customObservationConvention, DEFAULT_OBSERVATION_CONVENTION, () -> observationContext,
					this.observationRegistry)
			.observe(() -> this.doDelete(deleteDocIds));
	}

View on GitHub (pinned to 98a7beda4f)