{"record":{"id":"395382817bfbbf41","repo":"run-llama/llama_index","slug":"citableblock-content-must-contain-exactly-one-bloc","errorCode":null,"errorMessage":"CitableBlock content must contain exactly one block when provided as a list.","messagePattern":"CitableBlock content must contain exactly one block when provided as a list\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/base/llms/types.py","lineNumber":1066,"sourceCode":"class CitationBlock(BaseRecursiveContentBlock):\n    \"\"\"A representation of cited content from past messages.\"\"\"\n\n    block_type: Literal[\"citation\"] = \"citation\"\n    cited_content: Annotated[\n        Union[TextBlock, ImageBlock], Field(discriminator=\"block_type\")\n    ]\n    source: str\n    title: str\n    additional_location_info: Dict[str, int]\n\n    @field_validator(\"cited_content\", mode=\"before\")\n    @classmethod\n    def validate_cited_content(cls, v: Any) -> Any:\n        if isinstance(v, str):\n            return TextBlock(text=v)\n        if isinstance(v, list):\n            if len(v) != 1:\n                raise ValueError(\n                    \"CitableBlock content must contain exactly one block when provided as a list.\"\n                )\n            value = v[0]\n            if isinstance(value, str):\n                return TextBlock(text=value)\n            else:\n                return value\n        return v\n\n    @classmethod\n    def nested_blocks_field_name(self) -> str:\n        return \"cited_content\"\n\n    def can_merge(self, other: Self) -> bool:\n        \"\"\"Check if this block can be merged with another block of the same type.\"\"\"\n        # Only merge if cited_content is of the same type and is a TextBlock\n        if type(self.cited_content) is type(other.cited_content) and isinstance(\n            self.cited_content, TextBlock","sourceCodeStart":1048,"sourceCodeEnd":1084,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/base/llms/types.py#L1048-L1084","documentation":"Raised by CitableBlock's cited_content field validator when cited_content is supplied as a list whose length is not exactly 1. The model accepts a plain str, a single block, or a one-element list (whose element may be a str); multiple blocks are ambiguous for a citation and rejected.","triggerScenarios":"Constructing CitableBlock(cited_content=[TextBlock(...), TextBlock(...)]) (2+ items) or cited_content=[] (empty list); building citation objects from search hits without limiting to one block.","commonSituations":"Programmatically collecting multiple retrieved passages into one citation instead of creating one CitableBlock per passage; passing an empty list from a failed retrieval step.","solutions":["Create one CitableBlock per cited passage instead of one with many blocks.","If a list is used, ensure it has exactly one element (str or block).","Pass a plain string when the citation is simple text: cited_content=\"...\"."],"exampleFix":"# before\ncited = CitableBlock(cited_content=[TextBlock(text=p1), TextBlock(text=p2)], source=..., title=..., additional_location_info={})\n\n# after\ncited = [\n    CitableBlock(cited_content=TextBlock(text=p1), source=..., title=..., additional_location_info={}),\n    CitableBlock(cited_content=TextBlock(text=p2), source=..., title=..., additional_location_info={}),\n]","handlingStrategy":"validation","validationCode":"if isinstance(cited_content, list) and len(cited_content) != 1:\n    blocks = [CitableBlock(cited_content=c, source=s, title=t, additional_location_info=i) for c in cited_content]","typeGuard":"def is_valid_cited_content(v: Any) -> bool:\n    return isinstance(v, str) or (isinstance(v, list) and len(v) == 1)","tryCatchPattern":null,"preventionTips":["Model one citation per CitableBlock.","Unit-test citation builders against multi-passage retrieval results."],"tags":["llama-index","citation","validation","blocks"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}