langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-08-24 22:11:36 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

API request to start cloud workflow returns error with local_file upload as parameters #21934

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

Originally created by @LordSyd on GitHub (Jan 27, 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

1.11.4

Cloud or Self Hosted

Cloud

Steps to reproduce

Configure the user input node of a workflow to accept several custom files with .json as an extension. (See screenshots)

Image Image

I used Postman to test the requests, btw.

Upload the .json files via the upload endpoint.
Try to post a request to run a specific workflow with the files in the "inputs" object in the raw body, like this:
Endpoint: https://api.dify.ai/v1/workflows/{}workflow_id removed/run

{
    "inputs": {
        "correct_month_1": {
            "type": "custom",
            "upload_file_id": "{file_id removed}",
            "transfer_method": "local_file"
        },
        "month_to_check": {
            "type": "custom",
            "transfer_method": "local_file",
            "upload_file_id": "{file_id removed}"
        },
         "correct_month_2": {
            "type": "custom",
            "transfer_method": "local_file",
            "upload_file_id": "{file_id removed}"
        }
    },
    "response_mode": "blocking",
    "user": "{user_name removed}"
}

✔️ Expected Behavior

To not get the "transfer_method is required in file mapping" error, as the method is present in my request.

❌ Actual Behavior

This returns a HTTP 400 error with this message:

{
    "code": "invalid_param",
    "message": "transfer_method is required in file mapping",
    "status": 400
}
Originally created by @LordSyd on GitHub (Jan 27, 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 1.11.4 ### Cloud or Self Hosted Cloud ### Steps to reproduce Configure the user input node of a workflow to accept several custom files with .json as an extension. (See screenshots) <img width="507" height="338" alt="Image" src="https://github.com/user-attachments/assets/b9b259cf-8ffc-49f2-9ccc-a23ce76d0568" /> <img width="374" height="712" alt="Image" src="https://github.com/user-attachments/assets/72ff66ac-8485-4b86-a601-43aa99af41aa"/> I used Postman to test the requests, btw. Upload the .json files via the upload endpoint. Try to post a request to run a specific workflow with the files in the "inputs" object in the raw body, like this: Endpoint: `https://api.dify.ai/v1/workflows/{}workflow_id removed/run` ``` { "inputs": { "correct_month_1": { "type": "custom", "upload_file_id": "{file_id removed}", "transfer_method": "local_file" }, "month_to_check": { "type": "custom", "transfer_method": "local_file", "upload_file_id": "{file_id removed}" }, "correct_month_2": { "type": "custom", "transfer_method": "local_file", "upload_file_id": "{file_id removed}" } }, "response_mode": "blocking", "user": "{user_name removed}" } ``` ### ✔️ Expected Behavior To not get the "transfer_method is required in file mapping" error, as the method is present in my request. ### ❌ Actual Behavior This returns a HTTP 400 error with this message: ``` { "code": "invalid_param", "message": "transfer_method is required in file mapping", "status": 400 } ```
yindo added the 🐞 bugcloud labels 2026-02-21 20:14:54 -05:00
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

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

Hi @LordSyd! I'm Dosu and I’m helping the dify team.

The error happens because the workflow API expects file mappings in a top-level files array, not just inside the inputs object. Even if you include transfer_method in inputs, the backend requires each file to be listed in the files array with all required fields: type, transfer_method, and upload_file_id (and optionally variable matching your workflow variable name) example discussion.

Here’s the correct structure for your API request:

{
  "inputs": {
    "correct_month_1": {
      "type": "custom",
      "upload_file_id": "your-file-id-1",
      "transfer_method": "local_file"
    },
    "month_to_check": {
      "type": "custom",
      "upload_file_id": "your-file-id-2",
      "transfer_method": "local_file"
    },
    "correct_month_2": {
      "type": "custom",
      "upload_file_id": "your-file-id-3",
      "transfer_method": "local_file"
    }
  },
  "files": [
    {
      "variable": "correct_month_1",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "your-file-id-1"
    },
    {
      "variable": "month_to_check",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "your-file-id-2"
    },
    {
      "variable": "correct_month_2",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "your-file-id-3"
    }
  ],
  "response_mode": "blocking",
  "user": "your_user"
}

Make sure:

  • Each file input is referenced in both inputs and the files array.
  • The variable field in each file object matches the workflow variable name.
  • All required fields are present and correct.

If you change input types or structure in the workflow editor, republish the workflow so the backend recognizes the update details.

Recent backend changes enforce strict validation, so the request format must match exactly. If you still see errors after updating your request, double-check variable names and file IDs, and let me know if you need more help.

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 27, 2026): <!-- Greeting --> Hi @LordSyd! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify team. <!-- Answer --> The error happens because the workflow API expects file mappings in a top-level `files` array, not just inside the `inputs` object. Even if you include `transfer_method` in `inputs`, the backend requires each file to be listed in the `files` array with all required fields: `type`, `transfer_method`, and `upload_file_id` (and optionally `variable` matching your workflow variable name) [example](https://github.com/langgenius/dify/issues/29665#issuecomment-3653813432) [discussion](https://github.com/langgenius/dify/discussions/27226#discussioncomment-14745030). Here’s the correct structure for your API request: ```json { "inputs": { "correct_month_1": { "type": "custom", "upload_file_id": "your-file-id-1", "transfer_method": "local_file" }, "month_to_check": { "type": "custom", "upload_file_id": "your-file-id-2", "transfer_method": "local_file" }, "correct_month_2": { "type": "custom", "upload_file_id": "your-file-id-3", "transfer_method": "local_file" } }, "files": [ { "variable": "correct_month_1", "type": "custom", "transfer_method": "local_file", "upload_file_id": "your-file-id-1" }, { "variable": "month_to_check", "type": "custom", "transfer_method": "local_file", "upload_file_id": "your-file-id-2" }, { "variable": "correct_month_2", "type": "custom", "transfer_method": "local_file", "upload_file_id": "your-file-id-3" } ], "response_mode": "blocking", "user": "your_user" } ``` Make sure: - Each file input is referenced in both `inputs` and the `files` array. - The `variable` field in each file object matches the workflow variable name. - All required fields are present and correct. If you change input types or structure in the workflow editor, republish the workflow so the backend recognizes the update [details](https://github.com/langgenius/dify/issues/30867). Recent backend changes enforce strict validation, so the request format must match exactly. If you still see errors after updating your request, double-check variable names and file IDs, and let me know if you need more help. <!-- 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/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/4006bcb2-e16b-4dd7-8ff7-5cd9df2f413c?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%20error%20happens%20because%20the%20workflow%20API%20expects%20file%20mappings%20in%20a%20top-level%20%60files%60%20array%2C%20not%20just%20inside%20the%20%60inputs%60%20object.%20Even%20if%20you%20include%20%60transfer_method%60%20in%20%60inputs%60%2C%20the%20backend%20requires%20each%20file%20to%20be%20listed%20in%20the%20%60files%60%20array%20with%20all%20required%20fields%3A%20%60type%60%2C%20%60transfer_method%60%2C%20and%20%60upload_file_id%60%20%28and%20optionally%20%60variable%60%20matching%20your%20workflow%20variable%20name%29%C2%A0%5Bexample%5D%28https%3A//github.com/langgenius/dify/issues/29665%23issuecomment-3653813432%29%C2%A0%5Bdiscussion%5D%28https%3A//github.com/langgenius/dify/discussions/27226%23discussioncomment-14745030%29.%0A%0AHere%E2%80%99s%20the%20correct%20structure%20for%20your%20API%20request%3A%0A%0A%60%60%60json%0A%7B%0A%20%20%22inputs%22%3A%20%7B%0A%20%20%20%20%22correct_month_1%22%3A%20%7B%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-1%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22month_to_check%22%3A%20%7B%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-2%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22correct_month_2%22%3A%20%7B%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-3%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%0A%20%20%20%20%7D%0A%20%20%7D%2C%0A%20%20%22files%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22variable%22%3A%20%22correct_month_1%22%2C%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-1%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22variable%22%3A%20%22month_to_check%22%2C%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-2%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22variable%22%3A%20%22correct_month_2%22%2C%0A%20%20%20%20%20%20%22type%22%3A%20%22custom%22%2C%0A%20%20%20%20%20%20%22transfer_method%22%3A%20%22local_file%22%2C%0A%20%20%20%20%20%20%22upload_file_id%22%3A%20%22your-file-id-3%22%0A%20%20%20%20%7D%0A%20%20%5D%2C%0A%20%20%22response_mode%22%3A%20%22blocking%22%2C%0A%20%20%22user%22%3A%20%22your_user%22%0A%7D%0A%60%60%60%0A%0AMake%20sure%3A%0A-%20Each%20file%20input%20is%20referenced%20in%20both%20%60inputs%60%20and%20the%20%60files%60%20array.%0A-%20The%20%60variable%60%20field%20in%20each%20file%20object%20matches%20the%20workflow%20variable%20name.%0A-%20All%20required%20fields%20are%20present%20and%20correct.%0A%0AIf%20you%20change%20input%20types%20or%20structure%20in%20the%20workflow%20editor%2C%20republish%20the%20workflow%20so%20the%20backend%20recognizes%20the%20update%C2%A0%5Bdetails%5D%28https%3A//github.com/langgenius/dify/issues/30867%29.%0A%0ARecent%20backend%20changes%20enforce%20strict%20validation%2C%20so%20the%20request%20format%20must%20match%20exactly.%20If%20you%20still%20see%20errors%20after%20updating%20your%20request%2C%20double-check%20variable%20names%20and%20file%20IDs%2C%20and%20let%20me%20know%20if%20you%20need%20more%20help.)&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/31619)
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

@LordSyd commented on GitHub (Jan 27, 2026):

I copied and pasted your suggestion into Postman and tried it. I am still getting the same error:

Image
@LordSyd commented on GitHub (Jan 27, 2026): I copied and pasted your suggestion into Postman and tried it. I am still getting the same error: <img width="909" height="855" alt="Image" src="https://github.com/user-attachments/assets/b9099677-d664-4fea-9e7d-8de620e98322" />
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

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

The backend requires each file mapping in the top-level files array to have an exact, non-empty "transfer_method" field (case-sensitive), along with "type" and a valid "upload_file_id" that matches an uploaded file and your tenant. Even a small typo, invisible character, or mismatch in field names will trigger the "transfer_method is required in file mapping" error (source).

Here’s a troubleshooting checklist:

  • Double-check that every object in your files array has "transfer_method": "local_file" (all lowercase, no extra spaces or hidden characters).
  • Ensure "upload_file_id" is a valid UUID and matches a file you uploaded.
  • Make sure all field names are spelled and cased exactly as expected: transfer_method, upload_file_id, type, and (optionally) variable.
  • Try sending a minimal payload with just one file mapping to isolate the issue.
  • If you recently changed workflow inputs, republish the workflow before testing again.
  • Sometimes, Postman or copy-paste can introduce invisible characters—try retyping the field names or use a different API client to rule out formatting issues.

If you’re still stuck, feel free to share a redacted sample of your actual JSON payload (as sent) and I can help spot any subtle issues.

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 27, 2026): <!-- Answer --> The backend requires each file mapping in the top-level `files` array to have an exact, non-empty `"transfer_method"` field (case-sensitive), along with `"type"` and a valid `"upload_file_id"` that matches an uploaded file and your tenant. Even a small typo, invisible character, or mismatch in field names will trigger the `"transfer_method is required in file mapping"` error ([source](https://github.com/langgenius/dify/blob/144ef0880a55ac8f623247c4a795730be95d92ee/api/factories/file_factory.py#L67-L201)). Here’s a troubleshooting checklist: - Double-check that every object in your `files` array has `"transfer_method": "local_file"` (all lowercase, no extra spaces or hidden characters). - Ensure `"upload_file_id"` is a valid UUID and matches a file you uploaded. - Make sure all field names are spelled and cased exactly as expected: `transfer_method`, `upload_file_id`, `type`, and (optionally) `variable`. - Try sending a minimal payload with just one file mapping to isolate the issue. - If you recently changed workflow inputs, republish the workflow before testing again. - Sometimes, Postman or copy-paste can introduce invisible characters—try retyping the field names or use a different API client to rule out formatting issues. If you’re still stuck, feel free to share a redacted sample of your actual JSON payload (as sent) and I can help spot any subtle issues. <!-- 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/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/8ad8d50b-ee1e-4644-a84e-2840b7d05b83?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%20backend%20requires%20each%20file%20mapping%20in%20the%20top-level%20%60files%60%20array%20to%20have%20an%20exact%2C%20non-empty%20%60%22transfer_method%22%60%20field%20%28case-sensitive%29%2C%20along%20with%20%60%22type%22%60%20and%20a%20valid%20%60%22upload_file_id%22%60%20that%20matches%20an%20uploaded%20file%20and%20your%20tenant.%20Even%20a%20small%20typo%2C%20invisible%20character%2C%20or%20mismatch%20in%20field%20names%20will%20trigger%20the%20%60%22transfer_method%20is%20required%20in%20file%20mapping%22%60%20error%20%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/144ef0880a55ac8f623247c4a795730be95d92ee/api/factories/file_factory.py%23L67-L201%29%29.%0A%0AHere%E2%80%99s%20a%20troubleshooting%20checklist%3A%0A-%20Double-check%20that%20every%20object%20in%20your%20%60files%60%20array%20has%20%60%22transfer_method%22%3A%20%22local_file%22%60%20%28all%20lowercase%2C%20no%20extra%20spaces%20or%20hidden%20characters%29.%0A-%20Ensure%20%60%22upload_file_id%22%60%20is%20a%20valid%20UUID%20and%20matches%20a%20file%20you%20uploaded.%0A-%20Make%20sure%20all%20field%20names%20are%20spelled%20and%20cased%20exactly%20as%20expected%3A%20%60transfer_method%60%2C%20%60upload_file_id%60%2C%20%60type%60%2C%20and%20%28optionally%29%20%60variable%60.%0A-%20Try%20sending%20a%20minimal%20payload%20with%20just%20one%20file%20mapping%20to%20isolate%20the%20issue.%0A-%20If%20you%20recently%20changed%20workflow%20inputs%2C%20republish%20the%20workflow%20before%20testing%20again.%0A-%20Sometimes%2C%20Postman%20or%20copy-paste%20can%20introduce%20invisible%20characters%E2%80%94try%20retyping%20the%20field%20names%20or%20use%20a%20different%20API%20client%20to%20rule%20out%20formatting%20issues.%0A%0AIf%20you%E2%80%99re%20still%20stuck%2C%20feel%20free%20to%20share%20a%20redacted%20sample%20of%20your%20actual%20JSON%20payload%20%28as%20sent%29%20and%20I%20can%20help%20spot%20any%20subtle%20issues.)&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/31619)
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

@LordSyd commented on GitHub (Jan 27, 2026):

@dosu I also tried it via curl just to be sure:

$ curl --location 'https://api.dify.ai/v1/workflows/{id removed}/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {id removed}' \
--data '{
  "inputs": {
    "correct_month_1": {
      "type": "custom",
      "upload_file_id": "{id removed}",
      "transfer_method": "local_file"
    },
    "month_to_check": {
      "type": "custom",
      "upload_file_id": "{id removed}",
      "transfer_method": "local_file"
    },
    "correct_month_2": {
      "type": "custom",
      "upload_file_id": "{id removed}",
      "transfer_method": "local_file"
    }
  },
  "files": [
    {
      "variable": "correct_month_1",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{id removed}"
    },
    {
      "variable": "month_to_check",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{id removed}"
    },
    {
      "variable": "correct_month_2",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{id removed}"
    }
  ],
  "response_mode": "blocking",
  "user": "{id removed}"
}'
{"code":"invalid_param","message":"transfer_method is required in file mapping","status":400}

Also tried it with just one parameter set to required, same behaviour.

@LordSyd commented on GitHub (Jan 27, 2026): @dosu I also tried it via curl just to be sure: ```bash $ curl --location 'https://api.dify.ai/v1/workflows/{id removed}/run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {id removed}' \ --data '{ "inputs": { "correct_month_1": { "type": "custom", "upload_file_id": "{id removed}", "transfer_method": "local_file" }, "month_to_check": { "type": "custom", "upload_file_id": "{id removed}", "transfer_method": "local_file" }, "correct_month_2": { "type": "custom", "upload_file_id": "{id removed}", "transfer_method": "local_file" } }, "files": [ { "variable": "correct_month_1", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{id removed}" }, { "variable": "month_to_check", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{id removed}" }, { "variable": "correct_month_2", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{id removed}" } ], "response_mode": "blocking", "user": "{id removed}" }' {"code":"invalid_param","message":"transfer_method is required in file mapping","status":400} ``` Also tried it with just one parameter set to required, same behaviour.
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

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

This error is almost always caused by a mismatch between the workflow input configuration and the API payload, or by backend validation expecting different values than what’s documented.

Here’s what’s most likely happening:

  • The workflow input variable in the editor must be set to type File (not Text, Custom, or Other). If it’s not, the backend will reject file inputs—even if your payload looks correct. After changing input types, you must republish the workflow for the backend to recognize the update discussion issue.
  • The backend expects the "type" field in both inputs and files to be "document" for most file uploads—even for .json or other custom files. Using "custom" or other values often triggers this error. Try changing "type": "custom" to "type": "document" everywhere in your payload issue.
  • The "upload_file_id" must be the exact value returned from /files/upload and must belong to your tenant. Double-check you’re not using a resource ID or a file uploaded under a different API key issue.
  • Strict validation is enforced for cloud requests, so every field must match exactly. Even a small typo, wrong case, or extra space will cause this error source.

If you’ve confirmed all of the above and the error persists, try creating a minimal workflow with a single file input of type File and test with a simple .txt or .pdf file. If that works, the issue is likely with file type restrictions or workflow configuration.

Let me know if switching "type" to "document" and republishing the workflow resolves it!

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 27, 2026): <!-- Answer --> This error is almost always caused by a mismatch between the workflow input configuration and the API payload, or by backend validation expecting different values than what’s documented. Here’s what’s most likely happening: - The workflow input variable in the editor must be set to type **File** (not Text, Custom, or Other). If it’s not, the backend will reject file inputs—even if your payload looks correct. After changing input types, you must republish the workflow for the backend to recognize the update [discussion](https://github.com/langgenius/dify/discussions/27226) [issue](https://github.com/langgenius/dify/issues/30867). - The backend expects the `"type"` field in both `inputs` and `files` to be `"document"` for most file uploads—even for .json or other custom files. Using `"custom"` or other values often triggers this error. Try changing `"type": "custom"` to `"type": "document"` everywhere in your payload [issue](https://github.com/langgenius/dify/issues/19083). - The `"upload_file_id"` must be the exact value returned from `/files/upload` and must belong to your tenant. Double-check you’re not using a resource ID or a file uploaded under a different API key [issue](https://github.com/langgenius/dify/issues/30867). - Strict validation is enforced for cloud requests, so every field must match exactly. Even a small typo, wrong case, or extra space will cause this error [source](https://github.com/langgenius/dify/blob/144ef0880a55ac8f623247c4a795730be95d92ee/api/factories/file_factory.py#L67-L177). If you’ve confirmed all of the above and the error persists, try creating a minimal workflow with a single file input of type **File** and test with a simple .txt or .pdf file. If that works, the issue is likely with file type restrictions or workflow configuration. Let me know if switching `"type"` to `"document"` and republishing the workflow resolves it! <!-- 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/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/97ddbdb9-a50f-49eb-a7f8-d9223b5c8f06?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=This%20error%20is%20almost%20always%20caused%20by%20a%20mismatch%20between%20the%20workflow%20input%20configuration%20and%20the%20API%20payload%2C%20or%20by%20backend%20validation%20expecting%20different%20values%20than%20what%E2%80%99s%20documented.%0A%0AHere%E2%80%99s%20what%E2%80%99s%20most%20likely%20happening%3A%0A%0A-%20The%20workflow%20input%20variable%20in%20the%20editor%20must%20be%20set%20to%20type%20%2A%2AFile%2A%2A%20%28not%20Text%2C%20Custom%2C%20or%20Other%29.%20If%20it%E2%80%99s%20not%2C%20the%20backend%20will%20reject%20file%20inputs%E2%80%94even%20if%20your%20payload%20looks%20correct.%20After%20changing%20input%20types%2C%20you%20must%20republish%20the%20workflow%20for%20the%20backend%20to%20recognize%20the%20update%C2%A0%5Bdiscussion%5D%28https%3A//github.com/langgenius/dify/discussions/27226%29%C2%A0%5Bissue%5D%28https%3A//github.com/langgenius/dify/issues/30867%29.%0A-%20The%20backend%20expects%20the%20%60%22type%22%60%20field%20in%20both%20%60inputs%60%20and%20%60files%60%20to%20be%20%60%22document%22%60%20for%20most%20file%20uploads%E2%80%94even%20for%20.json%20or%20other%20custom%20files.%20Using%20%60%22custom%22%60%20or%20other%20values%20often%20triggers%20this%20error.%20Try%20changing%20%60%22type%22%3A%20%22custom%22%60%20to%20%60%22type%22%3A%20%22document%22%60%20everywhere%20in%20your%20payload%C2%A0%5Bissue%5D%28https%3A//github.com/langgenius/dify/issues/19083%29.%0A-%20The%20%60%22upload_file_id%22%60%20must%20be%20the%20exact%20value%20returned%20from%20%60/files/upload%60%20and%20must%20belong%20to%20your%20tenant.%20Double-check%20you%E2%80%99re%20not%20using%20a%20resource%20ID%20or%20a%20file%20uploaded%20under%20a%20different%20API%20key%C2%A0%5Bissue%5D%28https%3A//github.com/langgenius/dify/issues/30867%29.%0A-%20Strict%20validation%20is%20enforced%20for%20cloud%20requests%2C%20so%20every%20field%20must%20match%20exactly.%20Even%20a%20small%20typo%2C%20wrong%20case%2C%20or%20extra%20space%20will%20cause%20this%20error%C2%A0%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/144ef0880a55ac8f623247c4a795730be95d92ee/api/factories/file_factory.py%23L67-L177%29.%0A%0AIf%20you%E2%80%99ve%20confirmed%20all%20of%20the%20above%20and%20the%20error%20persists%2C%20try%20creating%20a%20minimal%20workflow%20with%20a%20single%20file%20input%20of%20type%20%2A%2AFile%2A%2A%20and%20test%20with%20a%20simple%20.txt%20or%20.pdf%20file.%20If%20that%20works%2C%20the%20issue%20is%20likely%20with%20file%20type%20restrictions%20or%20workflow%20configuration.%0A%0ALet%20me%20know%20if%20switching%20%60%22type%22%60%20to%20%60%22document%22%60%20and%20republishing%20the%20workflow%20resolves%20it%21)&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/31619)
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

@LordSyd commented on GitHub (Jan 28, 2026):

I tried all of your suggestions, @dosu, but nothing worked. At this stage, I believe this is a bug on your end.

@LordSyd commented on GitHub (Jan 28, 2026): I tried all of your suggestions, @dosu, but nothing worked. At this stage, I believe this is a bug on your end.
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

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

You've done everything right—your payload structure, field names, and workflow config all match what the backend expects, but the error still persists. Based on the backend validation logic, this message is only triggered if the transfer_method field is missing or empty in the file mapping, and your requests clearly include it "source".

Given that you've tested with both Postman and curl, tried single and multiple files, and followed all known workarounds, this strongly points to a backend bug or an undocumented edge case in Dify Cloud v1.11.4. Recent backend refactors in file handling don't mention a fix for this error, so it's likely not addressed yet "source".

To help the maintainers reproduce and diagnose the issue, it would be useful to share: your workflow export/config, the exact file metadata (extension, mime type), and a minimal failing payload (with sensitive info redacted). If you want, I can help you format or anonymize these details before sharing.

Let me know if you have any logs or backend responses that show more context—sometimes error traces or debug output can reveal subtle mismatches or validation failures. This will help get a fix prioritized.

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 28, 2026): <!-- Answer --> You've done everything right—your payload structure, field names, and workflow config all match what the backend expects, but the error still persists. Based on the backend validation logic, this message is only triggered if the `transfer_method` field is missing or empty in the file mapping, and your requests clearly include it ["source"](https://github.com/langgenius/dify/blob/78198c6452cc712607ce5ab3732926c06001bc3a/api/factories/file_factory.py#L74-L187). Given that you've tested with both Postman and curl, tried single and multiple files, and followed all known workarounds, this strongly points to a backend bug or an undocumented edge case in Dify Cloud v1.11.4. Recent backend refactors in file handling don't mention a fix for this error, so it's likely not addressed yet ["source"](https://github.com/langgenius/dify/pull/30638). To help the maintainers reproduce and diagnose the issue, it would be useful to share: your workflow export/config, the exact file metadata (extension, mime type), and a minimal failing payload (with sensitive info redacted). If you want, I can help you format or anonymize these details before sharing. Let me know if you have any logs or backend responses that show more context—sometimes error traces or debug output can reveal subtle mismatches or validation failures. This will help get a fix prioritized. <!-- 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/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/289851d6-e4bc-4e24-8318-caa4a6105f6f?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=You%27ve%20done%20everything%20right%E2%80%94your%20payload%20structure%2C%20field%20names%2C%20and%20workflow%20config%20all%20match%20what%20the%20backend%20expects%2C%20but%20the%20error%20still%20persists.%20Based%20on%20the%20backend%20validation%20logic%2C%20this%20message%20is%20only%20triggered%20if%20the%20%60transfer_method%60%20field%20is%20missing%20or%20empty%20in%20the%20file%20mapping%2C%20and%20your%20requests%20clearly%20include%20it%20%5B%22source%22%5D%28https%3A//github.com/langgenius/dify/blob/78198c6452cc712607ce5ab3732926c06001bc3a/api/factories/file_factory.py%23L74-L187%29.%0A%0AGiven%20that%20you%27ve%20tested%20with%20both%20Postman%20and%20curl%2C%20tried%20single%20and%20multiple%20files%2C%20and%20followed%20all%20known%20workarounds%2C%20this%20strongly%20points%20to%20a%20backend%20bug%20or%20an%20undocumented%20edge%20case%20in%20Dify%20Cloud%20v1.11.4.%20Recent%20backend%20refactors%20in%20file%20handling%20don%27t%20mention%20a%20fix%20for%20this%20error%2C%20so%20it%27s%20likely%20not%20addressed%20yet%20%5B%22source%22%5D%28https%3A//github.com/langgenius/dify/pull/30638%29.%0A%0ATo%20help%20the%20maintainers%20reproduce%20and%20diagnose%20the%20issue%2C%20it%20would%20be%20useful%20to%20share%3A%20your%20workflow%20export/config%2C%20the%20exact%20file%20metadata%20%28extension%2C%20mime%20type%29%2C%20and%20a%20minimal%20failing%20payload%20%28with%20sensitive%20info%20redacted%29.%20If%20you%20want%2C%20I%20can%20help%20you%20format%20or%20anonymize%20these%20details%20before%20sharing.%0A%0ALet%20me%20know%20if%20you%20have%20any%20logs%20or%20backend%20responses%20that%20show%20more%20context%E2%80%94sometimes%20error%20traces%20or%20debug%20output%20can%20reveal%20subtle%20mismatches%20or%20validation%20failures.%20This%20will%20help%20get%20a%20fix%20prioritized.)&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/31619)
yindo commented 2026-02-21 20:14:55 -05:00
Author
Owner
Copy Link
Copy Source

@LordSyd commented on GitHub (Jan 28, 2026):

So, I narrowed down what is causing the bug. See this screenshot:

Image

I had an additional user input declared, but marked as not required. It seems the api still expected to get a file input and mapping in the request and threw the "transfer method" error. Using this body it worked:

{
    "inputs": {
        "correct_month_1": {
            "type": "custom",
            "upload_file_id":"{removed}",
            "transfer_method": "local_file"
        },
        "month_to_check": {
            "type": "custom",
            "transfer_method": "local_file",
            "upload_file_id": "{removed}"
        },
                "correct_month_2": {
            "type": "custom",
            "transfer_method": "local_file",
            "upload_file_id": "{removed}"
        },
        "confluence_export": {
            "type": "document",
            "upload_file_id":"{removed}",
            "transfer_method": "local_file"
        }
    },
  "files": [
    {
      "variable": "correct_month_1",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{removed}"
    },
    {
      "variable": "month_to_check",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{removed}"
    },
    {
      "variable": "correct_month_2",
      "type": "custom",
      "transfer_method": "local_file",
      "upload_file_id": "{removed}"
    },
      {
      "variable": "confluence_export",
      "type": "document",
      "transfer_method": "local_file",
      "upload_file_id": "{removed}"
    }
  ],
    "response_mode": "blocking",
    "user": "daniel.kleissl"
}

But this means the "required" checkbox does nothing for file inputs if you start a workflow via API, because you always need to send all files and mappings in the request.

@LordSyd commented on GitHub (Jan 28, 2026): So, I narrowed down what is causing the bug. See this screenshot: <img width="873" height="862" alt="Image" src="https://github.com/user-attachments/assets/f349d675-1485-489b-80c9-aa4edaf5125b" /> I had an additional user input declared, but marked as not required. It seems the api still expected to get a file input and mapping in the request and threw the "transfer method" error. Using this body it worked: ```json { "inputs": { "correct_month_1": { "type": "custom", "upload_file_id":"{removed}", "transfer_method": "local_file" }, "month_to_check": { "type": "custom", "transfer_method": "local_file", "upload_file_id": "{removed}" }, "correct_month_2": { "type": "custom", "transfer_method": "local_file", "upload_file_id": "{removed}" }, "confluence_export": { "type": "document", "upload_file_id":"{removed}", "transfer_method": "local_file" } }, "files": [ { "variable": "correct_month_1", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{removed}" }, { "variable": "month_to_check", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{removed}" }, { "variable": "correct_month_2", "type": "custom", "transfer_method": "local_file", "upload_file_id": "{removed}" }, { "variable": "confluence_export", "type": "document", "transfer_method": "local_file", "upload_file_id": "{removed}" } ], "response_mode": "blocking", "user": "daniel.kleissl" } ``` But this means the "required" checkbox does nothing for file inputs if you start a workflow via API, because you always need to send all files and mappings in the request.
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 cloud 🐞 bug
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#21934
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?