spring-projects/spring-ai · error · IllegalArgumentException

Anthropic Citations API requires all documents to have consi

Error message

Anthropic Citations API requires all documents to have consistent citation settings. Either enable citations for all documents or disable for all documents.

What it means

AnthropicChatOptions.validateCitationConsistency enforces that all citation documents in the options either have citations enabled or all disabled, since the Anthropic Citations API rejects mixed settings within one request. If citationDocuments contains at least one document with citations enabled and one with citations disabled, IllegalArgumentException is thrown during validation (at request-build time).

Source

Thrown at models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java:375

	public @Nullable List<AnthropicCitationDocument> getCitationDocuments() {
		return this.citationDocuments;
	}

	/**
	 * Validate that all citation documents have consistent citation settings. Anthropic
	 * requires all documents to have citations enabled if any do.
	 */
	public void validateCitationConsistency() {
		if (CollectionUtils.isEmpty(this.citationDocuments)) {
			return;
		}

		boolean hasEnabledCitations = this.citationDocuments.stream()
			.anyMatch(AnthropicCitationDocument::isCitationsEnabled);
		boolean hasDisabledCitations = this.citationDocuments.stream().anyMatch(doc -> !doc.isCitationsEnabled());

		if (hasEnabledCitations && hasDisabledCitations) {
			throw new IllegalArgumentException(
					"Anthropic Citations API requires all documents to have consistent citation settings. "
							+ "Either enable citations for all documents or disable for all documents.");
		}
	}

	public AnthropicCacheOptions getCacheOptions() {
		return this.cacheOptions;
	}

	public @Nullable OutputConfig getOutputConfig() {
		return this.outputConfig;
	}

	public @Nullable Map<String, String> getHttpHeaders() {
		return this.httpHeaders;
	}

	public @Nullable AnthropicSkillContainer getSkillContainer() {

View on GitHub (pinned to 98a7beda4f)

Solutions

Set citationsEnabled=true on every document in the citationDocuments list when you want citations.
Or set citationsEnabled=false on all documents when you want none.
Normalize documents at construction time with a shared factory so all documents inherit the same citation setting.
Check any merge/append logic on options (copyOptions/merge) that could combine documents with different citation flags.

Example fix

// before
documents.add(pdfDoc.citationsEnabled(true));
documents.add(textDoc.citationsEnabled(false));
// after
documents.add(pdfDoc.citationsEnabled(true));
documents.add(textDoc.citationsEnabled(true));

Defensive patterns

Strategy: validation

Validate before calling

List<AnthropicCitationDocument> docs = options.getCitationDocuments();
boolean anyEnabled = docs.stream().anyMatch(AnthropicCitationDocument::isCitationsEnabled);
boolean allEnabled = docs.stream().allMatch(AnthropicCitationDocument::isCitationsEnabled);
if (!docs.isEmpty() && anyEnabled != allEnabled) {
    throw new IllegalArgumentException("All citation documents must share the same citationsEnabled setting");
}

Try / catch

try {
    return client.call(new Prompt(msg, options));
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("consistent citation settings")) {
        docs.forEach(d -> d.setCitationsEnabled(true));
        return client.call(new Prompt(msg, options));
    }
    throw e;
}

Prevention

Create all citation documents via one factory that fixes citationsEnabled uniformly.
Re-validate after any options merge or append of documents.
Assert citation consistency in tests for every request that uses citations.

When it happens

Trigger: Building AnthropicChatOptions whose citationDocuments list mixes AnthropicCitationDocument instances where isCitationsEnabled() is true for some and false for others, then using those options in a chat call.

Common situations: Merging documents from multiple sources (one configured with citations enabled, another defaulting to disabled); programmatic construction where a default document lacks the enabled flag; combining a new cited document with legacy uncited documents in the same request.

Related errors

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