{"record":{"id":"bac61054ce7e06b7","repo":"spring-projects/spring-ai","slug":"anthropic-citations-api-requires-all-documents-to","errorCode":null,"errorMessage":"Anthropic Citations API requires all documents to have consistent citation settings. Either enable citations for all documents or disable for all documents.","messagePattern":"Anthropic Citations API requires all documents to have consistent citation settings\\. Either enable citations for all documents or disable for all documents\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java","lineNumber":375,"sourceCode":"\tpublic @Nullable List<AnthropicCitationDocument> getCitationDocuments() {\n\t\treturn this.citationDocuments;\n\t}\n\n\t/**\n\t * Validate that all citation documents have consistent citation settings. Anthropic\n\t * requires all documents to have citations enabled if any do.\n\t */\n\tpublic void validateCitationConsistency() {\n\t\tif (CollectionUtils.isEmpty(this.citationDocuments)) {\n\t\t\treturn;\n\t\t}\n\n\t\tboolean hasEnabledCitations = this.citationDocuments.stream()\n\t\t\t.anyMatch(AnthropicCitationDocument::isCitationsEnabled);\n\t\tboolean hasDisabledCitations = this.citationDocuments.stream().anyMatch(doc -> !doc.isCitationsEnabled());\n\n\t\tif (hasEnabledCitations && hasDisabledCitations) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Anthropic Citations API requires all documents to have consistent citation settings. \"\n\t\t\t\t\t\t\t+ \"Either enable citations for all documents or disable for all documents.\");\n\t\t}\n\t}\n\n\tpublic AnthropicCacheOptions getCacheOptions() {\n\t\treturn this.cacheOptions;\n\t}\n\n\tpublic @Nullable OutputConfig getOutputConfig() {\n\t\treturn this.outputConfig;\n\t}\n\n\tpublic @Nullable Map<String, String> getHttpHeaders() {\n\t\treturn this.httpHeaders;\n\t}\n\n\tpublic @Nullable AnthropicSkillContainer getSkillContainer() {","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java#L357-L393","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndocuments.add(pdfDoc.citationsEnabled(true));\ndocuments.add(textDoc.citationsEnabled(false));\n// after\ndocuments.add(pdfDoc.citationsEnabled(true));\ndocuments.add(textDoc.citationsEnabled(true));","handlingStrategy":"validation","validationCode":"List<AnthropicCitationDocument> docs = options.getCitationDocuments();\nboolean anyEnabled = docs.stream().anyMatch(AnthropicCitationDocument::isCitationsEnabled);\nboolean allEnabled = docs.stream().allMatch(AnthropicCitationDocument::isCitationsEnabled);\nif (!docs.isEmpty() && anyEnabled != allEnabled) {\n    throw new IllegalArgumentException(\"All citation documents must share the same citationsEnabled setting\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return client.call(new Prompt(msg, options));\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"consistent citation settings\")) {\n        docs.forEach(d -> d.setCitationsEnabled(true));\n        return client.call(new Prompt(msg, options));\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["java","spring-ai","anthropic","citations","validation"],"backgroundTag":"conflicting-config-options","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}