langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-07-20 19:50:06 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

Multimodal RAG with/without images issues #21508

New Issue
Open
opened 2026-02-21 20:12:54 -05:00 by yindo · 15 comments
yindo commented 2026-02-21 20:12:54 -05:00
Owner
Copy Link
Copy Source

Originally created by @jlfloresTeika on GitHub (Jan 7, 2026).

Self Checks

  • I have read the Contributing Guide and Language Policy.
  • This is only for bug report, if you would like to ask a question, please head to Discussions.
  • I have searched for existing issues search for existing issues, including closed ones.
  • I confirm that I am using English to submit this report, otherwise it will be closed.
  • 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
  • Please do not modify this template :) and fill in all the required fields.

Dify version

latest docker release

Cloud or Self Hosted

Self Hosted (Docker)

Steps to reproduce

I did a Multimodal Knowledge with a docx containing images and text, I have created a tool workflow for an Agent to retrieve from the multimodal rag and I find this error consistently, error that in the non-multimodal rag workflows I don't find.

"tool_call_name": "multimodal_rag",
"tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type."

Image

When I enable the parameter for the images (files array) and feed my chat workflow that is linked with an agent to the multimodal_rag tool workflow the error is:

Object of type File is not JSON serializable

Image

Any help is appreciated, thanks DiFy team and contributors, this feature looks very promising!

For other details you may need to debug, i'm here. ty

✔️ Expected Behavior

The multimodal rag workflow should act like the non-multimodal regarding inputs and ouputs despite image input detail since is optional and it seems to not work as expected.

PD: When I test retrival directly from the retrieval tool it works good. That's why is strange that in an agent with the tool workflow attatched doesn't behave the same.

❌ Actual Behavior

The multimodal rag workflow tool I've configured doesn't behave as expected, I'm experiencing the avobe mentioned issues.

Originally created by @jlfloresTeika on GitHub (Jan 7, 2026). ### Self Checks - [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542). - [x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general). - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：） - [x] Please do not modify this template :) and fill in all the required fields. ### Dify version latest docker release ### Cloud or Self Hosted Self Hosted (Docker) ### Steps to reproduce I did a Multimodal Knowledge with a docx containing images and text, I have created a tool workflow for an Agent to retrieve from the multimodal rag and I find this error consistently, error that in the non-multimodal rag workflows I don't find. "tool_call_name": "multimodal_rag", "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type." <img width="599" height="504" alt="Image" src="https://github.com/user-attachments/assets/3228297d-4d8e-49de-a4f6-f007c3a7bbd4" /> When I enable the parameter for the images (files array) and feed my chat workflow that is linked with an agent to the multimodal_rag tool workflow the error is: Object of type File is not JSON serializable <img width="599" height="504" alt="Image" src="https://github.com/user-attachments/assets/64db032e-d58f-4b1c-9c4b-88ea2c795067" /> Any help is appreciated, thanks DiFy team and contributors, this feature looks very promising! For other details you may need to debug, i'm here. ty ### ✔️ Expected Behavior The multimodal rag workflow should act like the non-multimodal regarding inputs and ouputs despite image input detail since is optional and it seems to not work as expected. PD: When I test retrival directly from the retrieval tool it works good. That's why is strange that in an agent with the tool workflow attatched doesn't behave the same. ### ❌ Actual Behavior The multimodal rag workflow tool I've configured doesn't behave as expected, I'm experiencing the avobe mentioned issues.
yindo added the 👻 feat:ragstale labels 2026-02-21 20:12:54 -05:00
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Jan 7, 2026):

The errors you’re seeing are due to how Dify handles file/image attachments in multimodal RAG agent workflows. The “Object of type File is not JSON serializable” error happens when a File object is passed directly instead of being converted to a JSON-serializable format (like a dict with metadata and a URL). The “Attachments variable is not array file or file type” error means the input validation expects an array of file references, but the input doesn’t match—often because the files weren’t properly transformed to URLs or plugin-compatible dicts before being sent to the tool workflow.

Direct retrieval works because it handles file/image serialization differently, but agent tool workflows require explicit conversion. Dify’s code expects files to be passed as references (URLs, file IDs, or plugin-compatible dicts), not as raw File objects. The File class provides methods like .to_dict() and .to_plugin_parameter() for this purpose, and the ToolFileMessageTransformer is responsible for converting File objects into URLs or plugin parameters for serialization in workflows. If this transformation is skipped, serialization errors occur1.

To resolve this:

  • Ensure that any file/image attachments are passed as URLs or plugin-compatible dicts, not as raw File objects. Use .to_dict() or .to_plugin_parameter() if you’re working with custom plugins or integrations.
  • Make sure your workflow nodes are configured to output file/image references, and that the LLM node’s image input is connected with the “vision” feature enabled.
  • Set the environment variables MULTIMODAL_SEND_IMAGE_FORMAT (to url or base64, depending on your model’s requirements) and INTERNAL_FILES_URL (to a Docker-network-accessible URL) in your Docker deployment23.
  • Avoid referencing image/file variables in the System Prompt; only use them in User Prompts, as only User Prompts are serialized properly in current Dify versions4.
  • If you’re using official plugins, make sure you’re on the latest versions (OpenAI plugin >= 0.0.14, Azure OpenAI >= 0.0.11, OpenRouter >= 0.0.6) to avoid known serialization bugs5.

If you still see errors, double-check that all file/image data is correctly formatted and passed as references, and consider logging the serialized prompt messages before sending them to the plugin to debug further.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Jan 7, 2026): <!-- Answer --> The errors you’re seeing are due to how Dify handles file/image attachments in multimodal RAG agent workflows. The “Object of type File is not JSON serializable” error happens when a File object is passed directly instead of being converted to a JSON-serializable format (like a dict with metadata and a URL). The “Attachments variable is not array file or file type” error means the input validation expects an array of file references, but the input doesn’t match—often because the files weren’t properly transformed to URLs or plugin-compatible dicts before being sent to the tool workflow. Direct retrieval works because it handles file/image serialization differently, but agent tool workflows require explicit conversion. Dify’s code expects files to be passed as references (URLs, file IDs, or plugin-compatible dicts), not as raw File objects. The File class provides methods like `.to_dict()` and `.to_plugin_parameter()` for this purpose, and the ToolFileMessageTransformer is responsible for converting File objects into URLs or plugin parameters for serialization in workflows. If this transformation is skipped, serialization errors occur[1](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/utils/message_transformer.py#L20-L171). To resolve this: - Ensure that any file/image attachments are passed as URLs or plugin-compatible dicts, not as raw File objects. Use `.to_dict()` or `.to_plugin_parameter()` if you’re working with custom plugins or integrations. - Make sure your workflow nodes are configured to output file/image references, and that the LLM node’s image input is connected with the “vision” feature enabled. - Set the environment variables `MULTIMODAL_SEND_IMAGE_FORMAT` (to `url` or `base64`, depending on your model’s requirements) and `INTERNAL_FILES_URL` (to a Docker-network-accessible URL) in your Docker deployment[2](https://github.com/langgenius/dify/issues/27494)[3](https://github.com/langgenius/dify/discussions/30504#discussioncomment-15403678). - Avoid referencing image/file variables in the System Prompt; only use them in User Prompts, as only User Prompts are serialized properly in current Dify versions[4](https://github.com/langgenius/dify/discussions/30004#discussioncomment-15322810). - If you’re using official plugins, make sure you’re on the latest versions (OpenAI plugin >= 0.0.14, Azure OpenAI >= 0.0.11, OpenRouter >= 0.0.6) to avoid known serialization bugs[5](https://github.com/langgenius/dify/issues/16726#issuecomment-2750318418). If you still see errors, double-check that all file/image data is correctly formatted and passed as references, and consider logging the serialized prompt messages before sending them to the plugin to debug further. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/22543591-e1ea-40ba-9009-06af917e101f?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=The%20errors%20you%E2%80%99re%20seeing%20are%20due%20to%20how%20Dify%20handles%20file/image%20attachments%20in%20multimodal%20RAG%20agent%20workflows.%20The%20%E2%80%9CObject%20of%20type%20File%20is%20not%20JSON%20serializable%E2%80%9D%20error%20happens%20when%20a%20File%20object%20is%20passed%20directly%20instead%20of%20being%20converted%20to%20a%20JSON-serializable%20format%20%28like%20a%20dict%20with%20metadata%20and%20a%20URL%29.%20The%20%E2%80%9CAttachments%20variable%20is%20not%20array%20file%20or%20file%20type%E2%80%9D%20error%20means%20the%20input%20validation%20expects%20an%20array%20of%20file%20references%2C%20but%20the%20input%20doesn%E2%80%99t%20match%E2%80%94often%20because%20the%20files%20weren%E2%80%99t%20properly%20transformed%20to%20URLs%20or%20plugin-compatible%20dicts%20before%20being%20sent%20to%20the%20tool%20workflow.%0A%0ADirect%20retrieval%20works%20because%20it%20handles%20file/image%20serialization%20differently%2C%20but%20agent%20tool%20workflows%20require%20explicit%20conversion.%20Dify%E2%80%99s%20code%20expects%20files%20to%20be%20passed%20as%20references%20%28URLs%2C%20file%20IDs%2C%20or%20plugin-compatible%20dicts%29%2C%20not%20as%20raw%20File%20objects.%20The%20File%20class%20provides%20methods%20like%20%60.to_dict%28%29%60%20and%20%60.to_plugin_parameter%28%29%60%20for%20this%20purpose%2C%20and%20the%20ToolFileMessageTransformer%20is%20responsible%20for%20converting%20File%20objects%20into%20URLs%20or%20plugin%20parameters%20for%20serialization%20in%20workflows.%20If%20this%20transformation%20is%20skipped%2C%20serialization%20errors%20occur%5B1%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/utils/message_transformer.py%23L20-L171%29.%0A%0ATo%20resolve%20this%3A%0A-%20Ensure%20that%20any%20file/image%20attachments%20are%20passed%20as%20URLs%20or%20plugin-compatible%20dicts%2C%20not%20as%20raw%20File%20objects.%20Use%20%60.to_dict%28%29%60%20or%20%60.to_plugin_parameter%28%29%60%20if%20you%E2%80%99re%20working%20with%20custom%20plugins%20or%20integrations.%0A-%20Make%20sure%20your%20workflow%20nodes%20are%20configured%20to%20output%20file/image%20references%2C%20and%20that%20the%20LLM%20node%E2%80%99s%20image%20input%20is%20connected%20with%20the%20%E2%80%9Cvision%E2%80%9D%20feature%20enabled.%0A-%20Set%20the%20environment%20variables%20%60MULTIMODAL_SEND_IMAGE_FORMAT%60%20%28to%20%60url%60%20or%20%60base64%60%2C%20depending%20on%20your%20model%E2%80%99s%20requirements%29%20and%20%60INTERNAL_FILES_URL%60%20%28to%20a%20Docker-network-accessible%20URL%29%20in%20your%20Docker%20deployment%5B2%5D%28https%3A//github.com/langgenius/dify/issues/27494%29%5B3%5D%28https%3A//github.com/langgenius/dify/discussions/30504%23discussioncomment-15403678%29.%0A-%20Avoid%20referencing%20image/file%20variables%20in%20the%20System%20Prompt%3B%20only%20use%20them%20in%20User%20Prompts%2C%20as%20only%20User%20Prompts%20are%20serialized%20properly%20in%20current%20Dify%20versions%5B4%5D%28https%3A//github.com/langgenius/dify/discussions/30004%23discussioncomment-15322810%29.%0A-%20If%20you%E2%80%99re%20using%20official%20plugins%2C%20make%20sure%20you%E2%80%99re%20on%20the%20latest%20versions%20%28OpenAI%20plugin%20%3E%3D%200.0.14%2C%20Azure%20OpenAI%20%3E%3D%200.0.11%2C%20OpenRouter%20%3E%3D%200.0.6%29%20to%20avoid%20known%20serialization%20bugs%5B5%5D%28https%3A//github.com/langgenius/dify/issues/16726%23issuecomment-2750318418%29.%0A%0AIf%20you%20still%20see%20errors%2C%20double-check%20that%20all%20file/image%20data%20is%20correctly%20formatted%20and%20passed%20as%20references%2C%20and%20consider%20logging%20the%20serialized%20prompt%20messages%20before%20sending%20them%20to%20the%20plugin%20to%20debug%20further.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/30713)
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 7, 2026):

But when I don't send images as input since in the multimodal rag images are optional how is that the error is: "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type." ? also inside my agent workflow how can I convert the image / file inputs to serializable json like the tool expects? @dosu

@jlfloresTeika commented on GitHub (Jan 7, 2026): But when I don't send images as input since in the multimodal rag images are optional how is that the error is: "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type." ? also inside my agent workflow how can I convert the image / file inputs to serializable json like the tool expects? @dosu
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Jan 7, 2026):

That error happens because Dify expects the attachments variable to always be an array—even if it's empty—not null or another type. If your agent workflow sends attachments: null or omits the field, or if it accidentally passes a raw File object instead of a serializable value, you'll get the "Attachments variable is not array file or file type" error. The validator only accepts arrays of file references (dicts/URLs), not File objects or other types (source).

To fix this, always send attachments: [] when there are no images/files, or attachments: [file1, file2, ...] where each file is a dict (not a File object). To convert a File object to a serializable dict in your agent workflow, use file.to_dict() or file.to_plugin_parameter() (source). For example:

# If you have a list of File objects
attachments = [file.to_dict() for file in files]  # or file.to_plugin_parameter()
# If no files/images:
attachments = []

Then, pass attachments as part of your tool input payload:

{
  "attachments": []
}

or, with files:

{
  "attachments": [
    {
      "filename": "example.png",
      "mime_type": "image/png",
      "url": "https://your-signed-url",
      ...
    }
  ]
}

Never pass the File object itself—always use the dict. This will keep your workflow compatible with Dify's multimodal RAG input validation and serialization logic (source).

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Jan 7, 2026): <!-- Answer --> That error happens because Dify expects the attachments variable to always be an array—even if it's empty—not null or another type. If your agent workflow sends attachments: null or omits the field, or if it accidentally passes a raw File object instead of a serializable value, you'll get the "Attachments variable is not array file or file type" error. The validator only accepts arrays of file references (dicts/URLs), not File objects or other types ([source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/entities/tool_entities.py#L128-L345)). To fix this, always send attachments: [] when there are no images/files, or attachments: [file1, file2, ...] where each file is a dict (not a File object). To convert a File object to a serializable dict in your agent workflow, use file.to_dict() or file.to_plugin_parameter() ([source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/file/models.py#L36-L165)). For example: ```python # If you have a list of File objects attachments = [file.to_dict() for file in files] # or file.to_plugin_parameter() # If no files/images: attachments = [] ``` Then, pass attachments as part of your tool input payload: ```json { "attachments": [] } ``` or, with files: ```json { "attachments": [ { "filename": "example.png", "mime_type": "image/png", "url": "https://your-signed-url", ... } ] } ``` Never pass the File object itself—always use the dict. This will keep your workflow compatible with Dify's multimodal RAG input validation and serialization logic ([source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/utils/message_transformer.py#L20-L170)). <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/90a13608-2e81-4180-a995-864a870e231b?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=That%20error%20happens%20because%20Dify%20expects%20the%20attachments%20variable%20to%20always%20be%20an%20array%E2%80%94even%20if%20it%27s%20empty%E2%80%94not%20null%20or%20another%20type.%20If%20your%20agent%20workflow%20sends%20attachments%3A%20null%20or%20omits%20the%20field%2C%20or%20if%20it%20accidentally%20passes%20a%20raw%20File%20object%20instead%20of%20a%20serializable%20value%2C%20you%27ll%20get%20the%20%22Attachments%20variable%20is%20not%20array%20file%20or%20file%20type%22%20error.%20The%20validator%20only%20accepts%20arrays%20of%20file%20references%20%28dicts/URLs%29%2C%20not%20File%20objects%20or%20other%20types%20%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/entities/tool_entities.py%23L128-L345%29%29.%0A%0ATo%20fix%20this%2C%20always%20send%20attachments%3A%20%5B%5D%20when%20there%20are%20no%20images/files%2C%20or%20attachments%3A%20%5Bfile1%2C%20file2%2C%20...%5D%20where%20each%20file%20is%20a%20dict%20%28not%20a%20File%20object%29.%20To%20convert%20a%20File%20object%20to%20a%20serializable%20dict%20in%20your%20agent%20workflow%2C%20use%20file.to_dict%28%29%20or%20file.to_plugin_parameter%28%29%20%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/file/models.py%23L36-L165%29%29.%20For%20example%3A%0A%0A%60%60%60python%0A%23%20If%20you%20have%20a%20list%20of%20File%20objects%0Aattachments%20%3D%20%5Bfile.to_dict%28%29%20for%20file%20in%20files%5D%20%20%23%20or%20file.to_plugin_parameter%28%29%0A%23%20If%20no%20files/images%3A%0Aattachments%20%3D%20%5B%5D%0A%60%60%60%0A%0AThen%2C%20pass%20attachments%20as%20part%20of%20your%20tool%20input%20payload%3A%0A%0A%60%60%60json%0A%7B%0A%20%20%22attachments%22%3A%20%5B%5D%0A%7D%0A%60%60%60%0Aor%2C%20with%20files%3A%0A%60%60%60json%0A%7B%0A%20%20%22attachments%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22filename%22%3A%20%22example.png%22%2C%0A%20%20%20%20%20%20%22mime_type%22%3A%20%22image/png%22%2C%0A%20%20%20%20%20%20%22url%22%3A%20%22https%3A//your-signed-url%22%2C%0A%20%20%20%20%20%20...%0A%20%20%20%20%7D%0A%20%20%5D%0A%7D%0A%60%60%60%0A%0ANever%20pass%20the%20File%20object%20itself%E2%80%94always%20use%20the%20dict.%20This%20will%20keep%20your%20workflow%20compatible%20with%20Dify%27s%20multimodal%20RAG%20input%20validation%20and%20serialization%20logic%20%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/tools/utils/message_transformer.py%23L20-L170%29%29.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/30713)
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 7, 2026):

Thanks @dosu but is still not clear how to configure my workflow to convert the attachments variable to always be an array, is there a step-by-step that you could explain to me? In short, how to configure my nodes to work like the multimodal RAG expects. Thanks.

@jlfloresTeika commented on GitHub (Jan 7, 2026): Thanks @dosu but is still not clear how to configure my workflow to convert the attachments variable to always be an array, is there a step-by-step that you could explain to me? In short, how to configure my nodes to work like the multimodal RAG expects. Thanks.
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Jan 7, 2026):

Here’s how to configure your workflow so the attachments variable is always an array, as required by multimodal RAG:

  1. In the Dify workflow editor, make sure the node that provides files/images (like an upload or retrieval node) outputs a variable (e.g., attachments) and that this variable is set as a FILES type (not FILE). The FILES parameter type ensures that Dify always wraps the value as an array—even if it’s a single file or nothing at all. If no files are present, it will be an empty array, which is valid and prevents the “not array file or file type” error [source].

  2. When connecting nodes, always pass the attachments variable as-is to the tool node. If you’re using custom code or plugins, convert each File object to a dict using .to_dict() or .to_plugin_parameter() before passing it along. For example:

    attachments = [file.to_dict() for file in files]  # or file.to_plugin_parameter()
# If no files:
attachments = []

    Never pass raw File objects—always use their dict representation [source].

  3. If you’re not sending any files/images, make sure the attachments variable is set to an empty array ([]), not null or omitted. Dify’s backend will handle this correctly if the parameter is FILES type, but if you’re building payloads manually, always include "attachments": [].

  4. Example payloads:

    • With files: 
      {
  "attachments": [
    {
      "filename": "example.png",
      "mime_type": "image/png",
      "url": "https://your-signed-url"
    }
  ]
}
    • With no files: 
      {
  "attachments": []
}

  5. Common mistakes: Passing a File object directly (not serializable), omitting the attachments field, or using the wrong parameter type (FILE instead of FILES). Also, don’t reference image/file variables in the System Prompt—only in User Prompts.

  6. Debug tip: If you’re still seeing errors, log the attachments variable right before the tool node is invoked to confirm it’s always an array of dicts or an empty array.

This setup ensures your workflow is always compatible with multimodal RAG’s input validation and serialization logic [source].

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Jan 7, 2026): <!-- Answer --> Here’s how to configure your workflow so the attachments variable is always an array, as required by multimodal RAG: 1. **In the Dify workflow editor, make sure the node that provides files/images (like an upload or retrieval node) outputs a variable (e.g., `attachments`) and that this variable is set as a FILES type (not FILE).** The FILES parameter type ensures that Dify always wraps the value as an array—even if it’s a single file or nothing at all. If no files are present, it will be an empty array, which is valid and prevents the “not array file or file type” error [[source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/plugin/entities/parameters.py#L25-L176)]. 2. **When connecting nodes, always pass the attachments variable as-is to the tool node.** If you’re using custom code or plugins, convert each File object to a dict using `.to_dict()` or `.to_plugin_parameter()` before passing it along. For example: ```python attachments = [file.to_dict() for file in files] # or file.to_plugin_parameter() # If no files: attachments = [] ``` Never pass raw File objects—always use their dict representation [[source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/file/models.py#L36-L138)]. 3. **If you’re not sending any files/images, make sure the attachments variable is set to an empty array (`[]`), not `null` or omitted.** Dify’s backend will handle this correctly if the parameter is FILES type, but if you’re building payloads manually, always include `"attachments": []`. 4. **Example payloads:** - With files: ```json { "attachments": [ { "filename": "example.png", "mime_type": "image/png", "url": "https://your-signed-url" } ] } ``` - With no files: ```json { "attachments": [] } ``` 5. **Common mistakes:** Passing a File object directly (not serializable), omitting the attachments field, or using the wrong parameter type (FILE instead of FILES). Also, don’t reference image/file variables in the System Prompt—only in User Prompts. 6. **Debug tip:** If you’re still seeing errors, log the attachments variable right before the tool node is invoked to confirm it’s always an array of dicts or an empty array. This setup ensures your workflow is always compatible with multimodal RAG’s input validation and serialization logic [[source](https://github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/plugin/entities/parameters.py#L25-L176)]. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/d071b57f-da78-4bb8-8ed9-51fd8edba604?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=Here%E2%80%99s%20how%20to%20configure%20your%20workflow%20so%20the%20attachments%20variable%20is%20always%20an%20array%2C%20as%20required%20by%20multimodal%20RAG%3A%0A%0A1.%20%2A%2AIn%20the%20Dify%20workflow%20editor%2C%20make%20sure%20the%20node%20that%20provides%20files/images%20%28like%20an%20upload%20or%20retrieval%20node%29%20outputs%20a%20variable%20%28e.g.%2C%20%60attachments%60%29%20and%20that%20this%20variable%20is%20set%20as%20a%20FILES%20type%20%28not%20FILE%29.%2A%2A%20The%20FILES%20parameter%20type%20ensures%20that%20Dify%20always%20wraps%20the%20value%20as%20an%20array%E2%80%94even%20if%20it%E2%80%99s%20a%20single%20file%20or%20nothing%20at%20all.%20If%20no%20files%20are%20present%2C%20it%20will%20be%20an%20empty%20array%2C%20which%20is%20valid%20and%20prevents%20the%20%E2%80%9Cnot%20array%20file%20or%20file%20type%E2%80%9D%20error%20%5B%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/plugin/entities/parameters.py%23L25-L176%29%5D.%0A%0A2.%20%2A%2AWhen%20connecting%20nodes%2C%20always%20pass%20the%20attachments%20variable%20as-is%20to%20the%20tool%20node.%2A%2A%20If%20you%E2%80%99re%20using%20custom%20code%20or%20plugins%2C%20convert%20each%20File%20object%20to%20a%20dict%20using%20%60.to_dict%28%29%60%20or%20%60.to_plugin_parameter%28%29%60%20before%20passing%20it%20along.%20For%20example%3A%0A%20%20%20%60%60%60python%0A%20%20%20attachments%20%3D%20%5Bfile.to_dict%28%29%20for%20file%20in%20files%5D%20%20%23%20or%20file.to_plugin_parameter%28%29%0A%20%20%20%23%20If%20no%20files%3A%0A%20%20%20attachments%20%3D%20%5B%5D%0A%20%20%20%60%60%60%0A%20%20%20Never%20pass%20raw%20File%20objects%E2%80%94always%20use%20their%20dict%20representation%20%5B%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/file/models.py%23L36-L138%29%5D.%0A%0A3.%20%2A%2AIf%20you%E2%80%99re%20not%20sending%20any%20files/images%2C%20make%20sure%20the%20attachments%20variable%20is%20set%20to%20an%20empty%20array%20%28%60%5B%5D%60%29%2C%20not%20%60null%60%20or%20omitted.%2A%2A%20Dify%E2%80%99s%20backend%20will%20handle%20this%20correctly%20if%20the%20parameter%20is%20FILES%20type%2C%20but%20if%20you%E2%80%99re%20building%20payloads%20manually%2C%20always%20include%20%60%22attachments%22%3A%20%5B%5D%60.%0A%0A4.%20%2A%2AExample%20payloads%3A%2A%2A%0A%20%20%20-%20With%20files%3A%0A%20%20%20%20%20%60%60%60json%0A%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%22attachments%22%3A%20%5B%0A%20%20%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%22filename%22%3A%20%22example.png%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%22mime_type%22%3A%20%22image/png%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%22url%22%3A%20%22https%3A//your-signed-url%22%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%5D%0A%20%20%20%20%20%7D%0A%20%20%20%20%20%60%60%60%0A%20%20%20-%20With%20no%20files%3A%0A%20%20%20%20%20%60%60%60json%0A%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%22attachments%22%3A%20%5B%5D%0A%20%20%20%20%20%7D%0A%20%20%20%20%20%60%60%60%0A%0A5.%20%2A%2ACommon%20mistakes%3A%2A%2A%20Passing%20a%20File%20object%20directly%20%28not%20serializable%29%2C%20omitting%20the%20attachments%20field%2C%20or%20using%20the%20wrong%20parameter%20type%20%28FILE%20instead%20of%20FILES%29.%20Also%2C%20don%E2%80%99t%20reference%20image/file%20variables%20in%20the%20System%20Prompt%E2%80%94only%20in%20User%20Prompts.%0A%0A6.%20%2A%2ADebug%20tip%3A%2A%2A%20If%20you%E2%80%99re%20still%20seeing%20errors%2C%20log%20the%20attachments%20variable%20right%20before%20the%20tool%20node%20is%20invoked%20to%20confirm%20it%E2%80%99s%20always%20an%20array%20of%20dicts%20or%20an%20empty%20array.%0A%0AThis%20setup%20ensures%20your%20workflow%20is%20always%20compatible%20with%20multimodal%20RAG%E2%80%99s%20input%20validation%20and%20serialization%20logic%20%5B%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7ccf858ce61606ea4518a64ace44e4bbee4591b5/api/core/plugin/entities/parameters.py%23L25-L176%29%5D.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/30713)
yindo commented 2026-02-21 20:12:54 -05:00
Author
Owner
Copy Link
Copy Source

@fatelei commented on GitHub (Jan 8, 2026):

Self Checks

  • I have read the Contributing Guide and Language Policy.[x] This is only for bug report, if you would like to ask a question, please head to Discussions.[x] I have searched for existing issues search for existing issues, including closed ones.[x] I confirm that I am using English to submit this report, otherwise it will be closed.[x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）[x] Please do not modify this template :) and fill in all the required fields.

Dify version

latest docker release

Cloud or Self Hosted

Self Hosted (Docker)

Steps to reproduce

I did a Multimodal Knowledge with a docx containing images and text, I have created a tool workflow for an Agent to retrieve from the multimodal rag and I find this error consistently, error that in the non-multimodal rag workflows I don't find.

"tool_call_name": "multimodal_rag", "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type."

Image When I enable the parameter for the images (files array) and feed my chat workflow that is linked with an agent to the multimodal_rag tool workflow the error is:

Object of type File is not JSON serializable

Image Any help is appreciated, thanks DiFy team and contributors, this feature looks very promising!

For other details you may need to debug, i'm here. ty

✔️ Expected Behavior

The multimodal rag workflow should act like the non-multimodal regarding inputs and ouputs despite image input detail since is optional and it seems to not work as expected.

PD: When I test retrival directly from the retrieval tool it works good. That's why is strange that in an agent with the tool workflow attatched doesn't behave the same.

❌ Actual Behavior

The multimodal rag workflow tool I've configured doesn't behave as expected, I'm experiencing the avobe mentioned issues.

how about your dsl

@fatelei commented on GitHub (Jan 8, 2026): > ### Self Checks > * [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).[x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).[x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.[x] I confirm that I am using English to submit this report, otherwise it will be closed.[x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）[x] Please do not modify this template :) and fill in all the required fields. > > ### Dify version > latest docker release > > ### Cloud or Self Hosted > Self Hosted (Docker) > > ### Steps to reproduce > I did a Multimodal Knowledge with a docx containing images and text, I have created a tool workflow for an Agent to retrieve from the multimodal rag and I find this error consistently, error that in the non-multimodal rag workflows I don't find. > > "tool_call_name": "multimodal_rag", "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type." > > <img alt="Image" width="599" height="504" src="https://private-user-images.githubusercontent.com/118909828/533059267-3228297d-4d8e-49de-a4f6-f007c3a7bbd4.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Njc4NTAyNjQsIm5iZiI6MTc2Nzg0OTk2NCwicGF0aCI6Ii8xMTg5MDk4MjgvNTMzMDU5MjY3LTMyMjgyOTdkLTRkOGUtNDlkZS1hNGY2LWYwMDdjM2E3YmJkNC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwMTA4JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDEwOFQwNTI2MDRaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT02MjIxYWQzNzI5MzA0OWJmMDNlN2EzYmYyZjk5ZWVjNmYwNmEyZWNlYTUxMmRhNTg4NzU5YjMxYmFjMzVlZDlhJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.8xyquJpxLyW4Ze06PjWz1G7VvFYzBDl2M8lkRYq3bBQ"> > When I enable the parameter for the images (files array) and feed my chat workflow that is linked with an agent to the multimodal_rag tool workflow the error is: > > Object of type File is not JSON serializable > > <img alt="Image" width="599" height="504" src="https://private-user-images.githubusercontent.com/118909828/533060436-64db032e-d58f-4b1c-9c4b-88ea2c795067.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Njc4NTAyNjQsIm5iZiI6MTc2Nzg0OTk2NCwicGF0aCI6Ii8xMTg5MDk4MjgvNTMzMDYwNDM2LTY0ZGIwMzJlLWQ1OGYtNGIxYy05YzRiLTg4ZWEyYzc5NTA2Ny5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwMTA4JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDEwOFQwNTI2MDRaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1lODAwMWY5MGJjOTI3OTA0ZWEwZjRjODU0ZGMyYmNkZjg0MmJmZDQxYzEzYjA1YjM5MzJmZTI5YzU1MjJjYjRhJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.FStJ63jijAskVG5je-fuRAxQOfVD4iXwV7A-inWbm9I"> > Any help is appreciated, thanks DiFy team and contributors, this feature looks very promising! > > For other details you may need to debug, i'm here. ty > > ### ✔️ Expected Behavior > The multimodal rag workflow should act like the non-multimodal regarding inputs and ouputs despite image input detail since is optional and it seems to not work as expected. > > PD: When I test retrival directly from the retrieval tool it works good. That's why is strange that in an agent with the tool workflow attatched doesn't behave the same. > > ### ❌ Actual Behavior > The multimodal rag workflow tool I've configured doesn't behave as expected, I'm experiencing the avobe mentioned issues. how about your dsl
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 8, 2026):

MultimodalRAG.zip

Here are the DSL's, thanks @fatelei

@jlfloresTeika commented on GitHub (Jan 8, 2026): [MultimodalRAG.zip](https://github.com/user-attachments/files/24494412/MultimodalRAG.zip) Here are the DSL's, thanks @fatelei
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@fatelei commented on GitHub (Jan 8, 2026):

MultimodalRAG.zip

Here are the DSL's, thanks @fatelei

ok

@fatelei commented on GitHub (Jan 8, 2026): > [MultimodalRAG.zip](https://github.com/user-attachments/files/24494412/MultimodalRAG.zip) > > Here are the DSL's, thanks [@fatelei](https://github.com/fatelei) ok
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 8, 2026):

I believe it may be related to this pull request: https://github.com/langgenius/dify/pull/30177 @fatelei

For clarification:

despite not using the agent, when using just regular Knowledge retrieval node (with multimodal enabled) linked to a regular LLM node and final response node when I attatch any image it says the "Object of type File is not JSON serializable" error.

When doing the same (regular-every node in the same chat flow) without images, it works good, text retrieval succeeded,

but when I use an agent with a workflow as tool that has the Knowledge retrieval and outputs the response to the agent then the flow fails in both text-only retrieval (with tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type and Object of type File is not JSON serializable, depending if I attatch images to the user.query or not (shared DSL's).

Note:
When I use the Knowledge retrieval node with the multimodal dataset with the built-in node test feature, it works good in both cases, with and without images. Is when I connect it to other nodes and trying to setup the agentic retrieval when failures are present.

@jlfloresTeika commented on GitHub (Jan 8, 2026): I believe it may be related to this pull request: https://github.com/langgenius/dify/pull/30177 @fatelei For clarification: despite not using the agent, when using just regular Knowledge retrieval node (with multimodal enabled) linked to a regular LLM node and final response node when I attatch any image it says the "Object of type File is not JSON serializable" error. When doing the same (regular-every node in the same chat flow) without images, it works good, text retrieval succeeded, but when I use an agent with a workflow as tool that has the Knowledge retrieval and outputs the response to the agent then the flow fails in both text-only retrieval (with `tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type` and `Object of type File is not JSON serializable`, depending if I attatch images to the user.query or not (shared DSL's). Note: When I use the Knowledge retrieval node with the multimodal dataset with the built-in node test feature, it works good in both cases, with and without images. Is when I connect it to other nodes and trying to setup the agentic retrieval when failures are present.
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 12, 2026):

Hi, @fatelei do I need to provide more detail for debug or with the DSL is enough?

I used google vertex AI multimodal embedding and embedding was completed successfully, retrieval node tests are working.

The fact that the Knowledge Retrieval node works fine with text and images when using the included 'Test node' functionality (play button) suggest that the problem may be related about how the incoming data (from upstream nodes to the knowledge retrieval node) is being handled. I suspect this based on observations and logs that I sent here.

Hope it helps to uncover why this feature is not working as expected, since is a very good feature, It's a pity that it doesn't seem correctly wired into the node's / workflows standard way of handling input / output objects (prompts, llm outputs) data and media.

Let's see if @dosu have any recommendation to better isolate the issue.

Thanks.

@jlfloresTeika commented on GitHub (Jan 12, 2026): Hi, @fatelei do I need to provide more detail for debug or with the DSL is enough? I used google vertex AI multimodal embedding and embedding was completed successfully, retrieval node tests are working. The fact that the Knowledge Retrieval node works fine with text and images when using the included 'Test node' functionality (play button) suggest that the problem may be related about how the incoming data (from upstream nodes to the knowledge retrieval node) is being handled. I suspect this based on observations and logs that I sent here. Hope it helps to uncover why this feature is not working as expected, since is a very good feature, It's a pity that it doesn't seem correctly wired into the node's / workflows standard way of handling input / output objects (prompts, llm outputs) data and media. Let's see if @dosu have any recommendation to better isolate the issue. Thanks.
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Jan 12, 2026):

The DSL files are helpful for understanding your workflow structure, but they usually aren't enough to fully debug serialization and attachment issues in multimodal RAG workflows. To isolate the root cause, it's important to see the actual runtime data passed between nodes—especially how the attachments variable is structured (is it always an array, are raw File objects being passed, etc.).

There are also known limitations in Dify: currently, agents cannot directly pass uploaded files (like images) to workflow tools if the tool requires a file-type input (file, files, or system_files). The agent-to-tool logic skips or blocks tools with required file inputs, and there’s no configuration or prompt workaround for this as of now. Making the file input optional or using indirect approaches (like download links) are the only workarounds, but they may not fit all use cases (source).

To move forward, please provide a sample of the actual payload or log showing the attachments variable as it is passed from the upstream node to the Knowledge Retrieval node during workflow execution (not just in node tests). This will help determine if the issue is with serialization, array typing, or the agent-to-tool file passing limitation. If you confirm that your tool requires file-type input and is invoked by an agent, this limitation is likely the blocker.

Let me know if you can share a runtime payload or log, and I can help pinpoint the next step.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Jan 12, 2026): <!-- Answer --> The DSL files are helpful for understanding your workflow structure, but they usually aren't enough to fully debug serialization and attachment issues in multimodal RAG workflows. To isolate the root cause, it's important to see the actual runtime data passed between nodes—especially how the attachments variable is structured (is it always an array, are raw File objects being passed, etc.). There are also known limitations in Dify: currently, agents cannot directly pass uploaded files (like images) to workflow tools if the tool requires a file-type input (file, files, or system_files). The agent-to-tool logic skips or blocks tools with required file inputs, and there’s no configuration or prompt workaround for this as of now. Making the file input optional or using indirect approaches (like download links) are the only workarounds, but they may not fit all use cases [(source)](https://github.com/langgenius/dify/discussions/29294). To move forward, please provide a sample of the actual payload or log showing the attachments variable as it is passed from the upstream node to the Knowledge Retrieval node during workflow execution (not just in node tests). This will help determine if the issue is with serialization, array typing, or the agent-to-tool file passing limitation. If you confirm that your tool requires file-type input and is invoked by an agent, this limitation is likely the blocker. Let me know if you can share a runtime payload or log, and I can help pinpoint the next step. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=The%20DSL%20files%20are%20helpful%20for%20understanding%20your%20workflow%20structure%2C%20but%20they%20usually%20aren%27t%20enough%20to%20fully%20debug%20serialization%20and%20attachment%20issues%20in%20multimodal%20RAG%20workflows.%20To%20isolate%20the%20root%20cause%2C%20it%27s%20important%20to%20see%20the%20actual%20runtime%20data%20passed%20between%20nodes%E2%80%94especially%20how%20the%20attachments%20variable%20is%20structured%20%28is%20it%20always%20an%20array%2C%20are%20raw%20File%20objects%20being%20passed%2C%20etc.%29.%0A%0AThere%20are%20also%20known%20limitations%20in%20Dify%3A%20currently%2C%20agents%20cannot%20directly%20pass%20uploaded%20files%20%28like%20images%29%20to%20workflow%20tools%20if%20the%20tool%20requires%20a%20file-type%20input%20%28file%2C%20files%2C%20or%20system_files%29.%20The%20agent-to-tool%20logic%20skips%20or%20blocks%20tools%20with%20required%20file%20inputs%2C%20and%20there%E2%80%99s%20no%20configuration%20or%20prompt%20workaround%20for%20this%20as%20of%20now.%20Making%20the%20file%20input%20optional%20or%20using%20indirect%20approaches%20%28like%20download%20links%29%20are%20the%20only%20workarounds%2C%20but%20they%20may%20not%20fit%20all%20use%20cases%20%5B%28source%29%5D%28https%3A//github.com/langgenius/dify/discussions/29294%29.%0A%0ATo%20move%20forward%2C%20please%20provide%20a%20sample%20of%20the%20actual%20payload%20or%20log%20showing%20the%20attachments%20variable%20as%20it%20is%20passed%20from%20the%20upstream%20node%20to%20the%20Knowledge%20Retrieval%20node%20during%20workflow%20execution%20%28not%20just%20in%20node%20tests%29.%20This%20will%20help%20determine%20if%20the%20issue%20is%20with%20serialization%2C%20array%20typing%2C%20or%20the%20agent-to-tool%20file%20passing%20limitation.%20If%20you%20confirm%20that%20your%20tool%20requires%20file-type%20input%20and%20is%20invoked%20by%20an%20agent%2C%20this%20limitation%20is%20likely%20the%20blocker.%0A%0ALet%20me%20know%20if%20you%20can%20share%20a%20runtime%20payload%20or%20log%2C%20and%20I%20can%20help%20pinpoint%20the%20next%20step.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/30713)
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@fatelei commented on GitHub (Jan 12, 2026):

The DSL files are helpful for understanding your workflow structure, but they usually aren't enough to fully debug serialization and attachment issues in multimodal RAG workflows. To isolate the root cause, it's important to see the actual runtime data passed between nodes—especially how the attachments variable is structured (is it always an array, are raw File objects being passed, etc.).

There are also known limitations in Dify: currently, agents cannot directly pass uploaded files (like images) to workflow tools if the tool requires a file-type input (file, files, or system_files). The agent-to-tool logic skips or blocks tools with required file inputs, and there’s no configuration or prompt workaround for this as of now. Making the file input optional or using indirect approaches (like download links) are the only workarounds, but they may not fit all use cases (source).

To move forward, please provide a sample of the actual payload or log showing the attachments variable as it is passed from the upstream node to the Knowledge Retrieval node during workflow execution (not just in node tests). This will help determine if the issue is with serialization, array typing, or the agent-to-tool file passing limitation. If you confirm that your tool requires file-type input and is invoked by an agent, this limitation is likely the blocker.

Let me know if you can share a runtime payload or log, and I can help pinpoint the next step.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

Image i test it, it work

@fatelei commented on GitHub (Jan 12, 2026): > The DSL files are helpful for understanding your workflow structure, but they usually aren't enough to fully debug serialization and attachment issues in multimodal RAG workflows. To isolate the root cause, it's important to see the actual runtime data passed between nodes—especially how the attachments variable is structured (is it always an array, are raw File objects being passed, etc.). > > There are also known limitations in Dify: currently, agents cannot directly pass uploaded files (like images) to workflow tools if the tool requires a file-type input (file, files, or system_files). The agent-to-tool logic skips or blocks tools with required file inputs, and there’s no configuration or prompt workaround for this as of now. Making the file input optional or using indirect approaches (like download links) are the only workarounds, but they may not fit all use cases [(source)](https://github.com/langgenius/dify/discussions/29294). > > To move forward, please provide a sample of the actual payload or log showing the attachments variable as it is passed from the upstream node to the Knowledge Retrieval node during workflow execution (not just in node tests). This will help determine if the issue is with serialization, array typing, or the agent-to-tool file passing limitation. If you confirm that your tool requires file-type input and is invoked by an agent, this limitation is likely the blocker. > > Let me know if you can share a runtime payload or log, and I can help pinpoint the next step. > > _To reply, just mention [@dosu](https://go.dosu.dev/dosubot)._ > > How did I do? [Good](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/3c64d500-7461-4f64-bd40-9b3c5f16757d?feedback_type=other) > > [![Chat with Dosu](https://camo.githubusercontent.com/7c571478962a6b8a5d47cac74b6824c75e4f6731bba52377e6007f9150462923/68747470733a2f2f646f73752e6465762f646f73752d636861742d62616467652e737667)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github) [![Open in Cursor](https://camo.githubusercontent.com/bdf7dbded65ee585887f47e5fd6fa099ea0933088b4b03d02e83b4def50154d4/68747470733a2f2f646f73752e6465762f646f73752d696e2d637572736f722e737667)](https://cursor.com/link/prompt?text=The%20DSL%20files%20are%20helpful%20for%20understanding%20your%20workflow%20structure%2C%20but%20they%20usually%20aren%27t%20enough%20to%20fully%20debug%20serialization%20and%20attachment%20issues%20in%20multimodal%20RAG%20workflows.%20To%20isolate%20the%20root%20cause%2C%20it%27s%20important%20to%20see%20the%20actual%20runtime%20data%20passed%20between%20nodes%E2%80%94especially%20how%20the%20attachments%20variable%20is%20structured%20%28is%20it%20always%20an%20array%2C%20are%20raw%20File%20objects%20being%20passed%2C%20etc.%29.%0A%0AThere%20are%20also%20known%20limitations%20in%20Dify%3A%20currently%2C%20agents%20cannot%20directly%20pass%20uploaded%20files%20%28like%20images%29%20to%20workflow%20tools%20if%20the%20tool%20requires%20a%20file-type%20input%20%28file%2C%20files%2C%20or%20system_files%29.%20The%20agent-to-tool%20logic%20skips%20or%20blocks%20tools%20with%20required%20file%20inputs%2C%20and%20there%E2%80%99s%20no%20configuration%20or%20prompt%20workaround%20for%20this%20as%20of%20now.%20Making%20the%20file%20input%20optional%20or%20using%20indirect%20approaches%20%28like%20download%20links%29%20are%20the%20only%20workarounds%2C%20but%20they%20may%20not%20fit%20all%20use%20cases%20%5B%28source%29%5D%28https%3A//github.com/langgenius/dify/discussions/29294%29.%0A%0ATo%20move%20forward%2C%20please%20provide%20a%20sample%20of%20the%20actual%20payload%20or%20log%20showing%20the%20attachments%20variable%20as%20it%20is%20passed%20from%20the%20upstream%20node%20to%20the%20Knowledge%20Retrieval%20node%20during%20workflow%20execution%20%28not%20just%20in%20node%20tests%29.%20This%20will%20help%20determine%20if%20the%20issue%20is%20with%20serialization%2C%20array%20typing%2C%20or%20the%20agent-to-tool%20file%20passing%20limitation.%20If%20you%20confirm%20that%20your%20tool%20requires%20file-type%20input%20and%20is%20invoked%20by%20an%20agent%2C%20this%20limitation%20is%20likely%20the%20blocker.%0A%0ALet%20me%20know%20if%20you%20can%20share%20a%20runtime%20payload%20or%20log%2C%20and%20I%20can%20help%20pinpoint%20the%20next%20step.) [![Join Discord](https://camo.githubusercontent.com/7d2066700925db1e370d956834f9ea0e5bc92cecbe84963fbd2a363e45091b4e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6a6f696e2d3538363546323f6c6f676f3d646973636f7264266c6f676f436f6c6f723d7768697465266c6162656c3d)](https://go.dosu.dev/discord-bot) [![Share on X](https://camo.githubusercontent.com/a8bd7f3fcf3f5e3bd124eee9ae50ae2ac17b40971726665ac2121d48f9aee155/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f582d73686172652d626c61636b)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/30713) <img width="3236" height="1696" alt="Image" src="https://github.com/user-attachments/assets/0216e342-789d-436f-97fb-0f4808e18a7f" /> i test it, it work
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@jlfloresTeika commented on GitHub (Jan 13, 2026):

Hi @fatelei thanks for testing and help me to isolate the issue, I tested and is not working in my chat flow:

Image

Agent log:
"tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type."
}

@jlfloresTeika commented on GitHub (Jan 13, 2026): Hi @fatelei thanks for testing and help me to isolate the issue, I tested and is not working in my chat flow: <img width="1688" height="808" alt="Image" src="https://github.com/user-attachments/assets/1c713512-6c76-4f09-85f0-540dae84d879" /> Agent log: "tool_response": "tool invoke error: read tool response failed: request failed: Attachments variable is not array file or file type." }
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@fatelei commented on GitHub (Jan 13, 2026):

we test different dsl, i try another

@fatelei commented on GitHub (Jan 13, 2026): we test different dsl, i try another
yindo commented 2026-02-21 20:12:55 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Feb 13, 2026):

Hi, @jlfloresTeika. I'm Dosu, and I'm helping the Dify team manage their backlog and am marking this issue as stale.

Issue Summary:

  • You reported errors in a self-hosted Docker multimodal RAG workflow related to improper serialization of File objects.
  • The errors include "Attachments variable is not array file or file type" and "Object of type File is not JSON serializable."
  • I provided guidance to pass attachments as arrays of dicts and configure workflow nodes with FILES type parameters.
  • A known limitation exists where agents cannot directly pass uploaded files to tools requiring file inputs; I suggested workarounds.
  • Despite sharing DSL files and logs, the issue persists in agent workflows, and I requested runtime payload samples for further diagnosis.

Next Steps:

  • Please confirm if this issue is still relevant with the latest version of Dify by commenting here to keep the discussion open.
  • Otherwise, this issue will be automatically closed in 15 days.

Thank you for your understanding and contribution!

@dosubot[bot] commented on GitHub (Feb 13, 2026): Hi, @jlfloresTeika. I'm [Dosu](https://dosu.dev), and I'm helping the Dify team manage their backlog and am marking this issue as stale. **Issue Summary:** - You reported errors in a self-hosted Docker multimodal RAG workflow related to improper serialization of File objects. - The errors include "Attachments variable is not array file or file type" and "Object of type File is not JSON serializable." - I provided guidance to pass attachments as arrays of dicts and configure workflow nodes with FILES type parameters. - A known limitation exists where agents cannot directly pass uploaded files to tools requiring file inputs; I suggested workarounds. - Despite sharing DSL files and logs, the issue persists in agent workflows, and I requested runtime payload samples for further diagnosis. **Next Steps:** - Please confirm if this issue is still relevant with the latest version of Dify by commenting here to keep the discussion open. - Otherwise, this issue will be automatically closed in 15 days. Thank you for your understanding and contribution!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Knowledge Pipeline
Proposal
WIP
cloud
dependencies
feat:webapp
good first issue
outdated
performance
pull-request
Mirrored from GitHub Pull Request
 python:uv
refactor
size:L
stale
status: accepting prs
status: blocked
status: in discussion
stt & tts
vulnerablity
web
wont-fix
🌊 feat:workflow
🌚 invalid
🐞 bug
👻 feat:rag
💪 enhancement
📚 documentation
🔨 feat:tools
🙋‍♂️ question
🙏 help wanted
🤔 cant-reproduce
🤖 feat:agent
No Label stale 👻 feat:rag
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify#21508
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?