{"record":{"id":"0753382c58453b76","repo":"langchain-ai/langchain","slug":"openai-chat-completions-does-not-support-file-urls","errorCode":null,"errorMessage":"OpenAI Chat Completions does not support file URLs.","messagePattern":"OpenAI Chat Completions does not support file URLs\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/messages/block_translators/openai.py","lineNumber":129,"sourceCode":"                    \" in the content block, e.g.: {'type': 'file', 'mime_type': \"\n                    \"'...', 'base64': '...', 'filename': 'my-file.pdf'}. \"\n                    \"Using placeholder filename 'LC_AUTOGENERATED'.\",\n                    stacklevel=1,\n                )\n            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.\"","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/messages/block_translators/openai.py#L111-L147","documentation":"Raised when a file content block with a `url` key is formatted for the OpenAI Chat Completions API (`api=\"chat/completions\"`). Chat Completions has no `file_url` input field — remote file URLs are only accepted by the newer Responses API, so the converter refuses rather than sending a request OpenAI would reject.","triggerScenarios":"Sending a file block like `{\"type\": \"file\", \"url\": \"https://...\"}` through a Chat Completions model or calling `convert_to_openai_data_block(block, api=\"chat/completions\")` on it.","commonSituations":"Switching an app between Responses and Chat Completions model bindings while keeping file-URL blocks; assuming the two OpenAI APIs share the same multimodal input schema; PDFs hosted on a CDN passed to `gpt-4o`-style chat models.","solutions":["Switch to a Responses-API model binding so the URL is emitted as `input_file.file_url`","Or download the file and send it as base64 with `mime_type` (e.g. `application/pdf`) on Chat Completions","Or upload the file to OpenAI and reference it by `file_id` instead of URL"],"exampleFix":"# before\nblock = {\"type\": \"file\", \"url\": \"https://example.com/doc.pdf\"}\nresp = chat_model.invoke([HumanMessage(content=[block])])  # Chat Completions -> ValueError\n\n# after\nimport base64\nb64 = base64.b64encode(requests.get(url).content).decode()\nblock = {\"type\": \"file\", \"base64\": b64, \"mime_type\": \"application/pdf\"}","handlingStrategy":"validation","validationCode":"def file_url_allowed(block: dict, api: str) -> bool:\n    if block.get(\"type\") == \"file\" and \"url\" in block:\n        return api == \"responses\"\n    return True","typeGuard":null,"tryCatchPattern":"try:\n    out = convert_to_openai_data_block(block, api=\"chat/completions\")\nexcept ValueError as e:\n    if \"does not support file URLs\" in str(e):\n        out = convert_to_openai_data_block(download_to_b64(block), api=\"chat/completions\")\n    else:\n        raise","preventionTips":["Know which OpenAI API surface your model binding targets before sending file URLs","Standardize on base64 or file_id for Chat Completions file inputs","Encapsulate file-block building in one helper that picks the right source per API"],"tags":["openai","chat-completions","responses-api","file","url"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}