{"record":{"id":"48e976212a76dbf4","repo":"langchain-ai/langchain","slug":"unrecognized-content-block-at-messages-i-conten-48e976","errorCode":null,"errorMessage":"Unrecognized content block at messages[{i}].content[{j}] has 'type': 'image_url' but is missing expected key(s) {missing}. Full content block:\n\n{block}","messagePattern":"Unrecognized content block at messages\\[(.+?)\\]\\.content\\[(.+?)\\] has 'type': 'image_url' but is missing expected key\\(s\\) (.+?)\\. Full content block:\n\n(.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/messages/utils.py","lineNumber":1707,"sourceCode":"                elif block.get(\"type\") == \"text\":\n                    if missing := [k for k in (\"text\",) if k not in block]:\n                        err = (\n                            f\"Unrecognized content block at \"\n                            f\"messages[{i}].content[{j}] has 'type': 'text' \"\n                            f\"but is missing expected key(s) \"\n                            f\"{missing}. Full content block:\\n\\n{block}\"\n                        )\n                        raise ValueError(err)\n                    content.append({\"type\": block[\"type\"], \"text\": block[\"text\"]})\n                elif block.get(\"type\") == \"image_url\":\n                    if missing := [k for k in (\"image_url\",) if k not in block]:\n                        err = (\n                            f\"Unrecognized content block at \"\n                            f\"messages[{i}].content[{j}] has 'type': 'image_url' \"\n                            f\"but is missing expected key(s) \"\n                            f\"{missing}. Full content block:\\n\\n{block}\"\n                        )\n                        raise ValueError(err)\n                    content.append(\n                        {\n                            \"type\": \"image_url\",\n                            \"image_url\": block[\"image_url\"],\n                        }\n                    )\n                # Standard multi-modal content block\n                elif is_data_content_block(block):\n                    formatted_block = convert_to_openai_data_block(block)\n                    if (\n                        formatted_block.get(\"type\") == \"file\"\n                        and \"file\" in formatted_block\n                        and \"filename\" not in formatted_block[\"file\"]\n                    ):\n                        logger.info(\"Generating a fallback filename.\")\n                        formatted_block[\"file\"][\"filename\"] = \"LC_AUTOGENERATED\"\n                    content.append(formatted_block)\n                # Anthropic and Bedrock converse format","sourceCodeStart":1689,"sourceCodeEnd":1725,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/messages/utils.py#L1689-L1725","documentation":"Raised by `convert_to_openai_messages` when a content block declares `'type': 'image_url'` but lacks the nested 'image_url' key. The converter must read `block['image_url']['url']` to build the OpenAI image payload, so the key is mandatory and the full block is echoed in the error.","triggerScenarios":"A block like `{'type': 'image_url'}` or `{'type': 'image_url', 'url': 'https://...'}` (url placed at the top level instead of nested under 'image_url').","commonSituations":"Flattened image blocks copied from curl examples; converting Gemini/Anthropic image shapes by hand and forgetting the nesting; the nested dict present but keyed differently.","solutions":["Nest the URL: `{'type': 'image_url', 'image_url': {'url': '<url or data URI>'}}`","If starting from base64 data, build a data URI: `f'data:{media_type};base64,{b64}'` inside `image_url.url`","Use the echoed block in the error message to spot the wrong key shape"],"exampleFix":"# before\n{'type': 'image_url', 'url': 'https://example.com/cat.png'}\n\n# after\n{'type': 'image_url', 'image_url': {'url': 'https://example.com/cat.png'}}","handlingStrategy":"validation","validationCode":"def valid_image_url_block(b: dict) -> bool:\n    return b.get('type') == 'image_url' and isinstance(b.get('image_url'), dict) and 'url' in b['image_url']\n\n# normalize common mistake: flat url\nif isinstance(b, dict) and b.get('type') == 'image_url' and 'url' in b and 'image_url' not in b:\n    b = {'type': 'image_url', 'image_url': {'url': b['url']}}","typeGuard":"def is_wellformed_image_url_block(b: object) -> bool:\n    return (isinstance(b, dict) and b.get('type') == 'image_url'\n            and isinstance(b.get('image_url'), dict) and 'url' in b['image_url'])","tryCatchPattern":null,"preventionTips":["Always nest the URL under the 'image_url' key","Wrap base64 images as data URIs: f'data:{media_type};base64,{data}'","Copy the exact block shape from the OpenAI multimodal docs"],"tags":["openai","content-blocks","multimodal","images"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}