{"record":{"id":"59214471b9243aae","repo":"langchain-ai/langchain","slug":"keys-base64-url-or-file-id-required-for-file-blo","errorCode":null,"errorMessage":"Keys base64, url, or file_id required for file blocks.","messagePattern":"Keys base64, url, or file_id required for file blocks\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/messages/block_translators/openai.py","lineNumber":134,"sourceCode":"            formatted_block = {\"type\": \"file\", \"file\": file}\n            if api == \"responses\":\n                formatted_block = {\"type\": \"input_file\", **formatted_block[\"file\"]}\n        elif block.get(\"source_type\") == \"id\" or \"file_id\" in block:\n            # Handle v0 format (IDContentBlock): {\"source_type\": \"id\", \"id\": \"...\", ...}\n            # Handle v1 format (IDCB): {\"file_id\": \"...\", ...}\n            file_id = block[\"id\"] if \"source_type\" in block else block[\"file_id\"]\n            formatted_block = {\"type\": \"file\", \"file\": {\"file_id\": file_id}}\n            if api == \"responses\":\n                formatted_block = {\"type\": \"input_file\", **formatted_block[\"file\"]}\n        elif \"url\" in block:  # Intentionally do not check for source_type=\"url\"\n            if api == \"chat/completions\":\n                error_msg = \"OpenAI Chat Completions does not support file URLs.\"\n                raise ValueError(error_msg)\n            # Only supported by Responses API; return in that format\n            formatted_block = {\"type\": \"input_file\", \"file_url\": block[\"url\"]}\n        else:\n            error_msg = \"Keys base64, url, or file_id required for file blocks.\"\n            raise ValueError(error_msg)\n\n    elif block[\"type\"] == \"audio\":\n        if \"base64\" in block or block.get(\"source_type\") == \"base64\":\n            # Handle v0 format: {\"source_type\": \"base64\", \"data\": \"...\", ...}\n            # Handle v1 format: {\"base64\": \"...\", ...}\n            base64_data = block[\"data\"] if \"source_type\" in block else block[\"base64\"]\n            audio_format = block[\"mime_type\"].split(\"/\")[-1]\n            formatted_block = {\n                \"type\": \"input_audio\",\n                \"input_audio\": {\"data\": base64_data, \"format\": audio_format},\n            }\n        else:\n            error_msg = \"Key base64 is required for audio blocks.\"\n            raise ValueError(error_msg)\n    else:\n        error_msg = f\"Block of type {block['type']} is not supported.\"\n        raise ValueError(error_msg)\n","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/messages/block_translators/openai.py#L116-L152","documentation":"Raised when a file content block sent to the OpenAI converter contains none of the recognized source keys: `base64`/`source_type==\"base64\"`, `id`/`file_id`, or `url`. The formatter cannot build an OpenAI file input without knowing where the file bytes or reference live.","triggerScenarios":"Passing `{\"type\": \"file\", ...}` with only metadata (`mime_type`, `name`, `id`-as-block-id) and no `file_id`/`base64`/`url`; blocks with typo'd source keys; file blocks stripped by serialization/deserialization that dropped the source field.","commonSituations":"Hand-written file blocks missing the source key; LangChain-serialized messages where the file payload key was renamed between versions; copying example blocks that were truncated for brevity.","solutions":["Add exactly one of `base64` (+ `mime_type`), `file_id`, or `url` to the file block","Use the v1 constructor `FileContentBlock(...)` which validates a source is present before this converter runs","Log the offending block before invoke() to spot which key was dropped"],"exampleFix":"# before\nblock = {\"type\": \"file\", \"mime_type\": \"application/pdf\"}\n\n# after\nblock = {\"type\": \"file\", \"file_id\": \"file-abc123\", \"mime_type\": \"application/pdf\"}","handlingStrategy":"validation","validationCode":"def has_file_source(block: dict) -> bool:\n    return any(k in block for k in (\"base64\", \"url\", \"file_id\")) or block.get(\"source_type\") == \"base64\"","typeGuard":"def is_valid_file_block(block: dict) -> bool:\n    return block.get(\"type\") == \"file\" and (\n        \"base64\" in block or \"url\" in block or \"file_id\" in block\n    )","tryCatchPattern":null,"preventionTips":["Always set exactly one source key when building file blocks","Use FileContentBlock(...) helpers which validate sources at construction","Assert block integrity after (de)serializing messages between services"],"tags":["openai","file","content-blocks","validation"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}