Why is the userinput.files parameter empty even though I have set the files parameter?

[blackheyan]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

When I call the chatflow, my parameters are as shown in the figure. However, userinput.files is null inside the chatflow. My version is 3.9.5.

[dosubot[bot]]

@blackheyan There are a couple of common reasons why userinput.files (i.e. sys.files) can be empty even when you pass a files parameter in the API call.

Most common cause: user parameter mismatch

Dify's file access controller enforces strict ownership. The user string you pass in /v1/files/upload must be byte-for-byte identical to the user string in your /v1/chat-messages call. If they differ (even by casing or whitespace), the file lookup fails silently and sys.files ends up empty [1]. This ownership check became stricter in recent Dify versions — it used to work even with inconsistent user values but no longer does [2].

File Upload feature not enabled

In the chatflow's generator, if FileUploadConfigManager.convert() returns no config (because File Upload is not enabled in the app's Features settings), file_objs is set to [] regardless of what you pass in the API call [3].

Things to check:

1. Same user value — confirm the user string is identical in both your /v1/files/upload and /v1/chat-messages requests.
2. File Upload enabled — in the chatflow's Features settings, verify "File Upload" is toggled on and the allowed file types include what you're sending.
3. Same API key — both calls must use the same app's API key; files scoped to one app cannot be accessed by another.
4. Correct request format — the files array in /v1/chat-messages should look like:

   {
     "files": [
       {
         "type": "document",
         "transfer_method": "local_file",
         "upload_file_id": "<id from upload response>"
       }
     ]
   }

One clarifying question: are you referencing sys.files (the built-in system variable) inside your chatflow, or a custom file variable you added to the Start node? Files passed via the top-level files API field go into sys.files automatically [4]. A custom Start node file variable would instead need to be passed under inputs, not the top-level files field.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.