dify - 💡(How to fix) Fix Workflow Tool optional file-list input fails when parent workflow passes an unset variable

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

Current origin/main source, commit 1c0080be6f1e34b7226bb3ca1b356d733680d48f.

Cloud or Self Hosted

Self Hosted (Source)

Steps to reproduce

1. Create a workflow that has a Start variable named images.
2. Set images to file-list / array of files, and set it as optional.
3. Publish that workflow as a Workflow Tool.
4. Create another workflow or pipeline with its own optional Start variable named images, also a file-list.
5. Add a Tool node in the parent workflow/pipeline and select the Workflow Tool from step 3.
6. For the tool parameter images, select the parent workflow variable images.
   • In the Tool node UI, this file-list parameter can only select an upstream variable. It cannot be manually set to an empty constant array [].
7. Run the parent workflow/pipeline without providing any files for images.

The error is raised while the current/parent workflow is invoking the Tool node. It is not raised by an internal node inside the child workflow, because the child workflow does not get a chance to handle the empty value.

Observed error:

images in input form must be a list of files

This appears related to closed issues such as #32566 and #28947, but the current Workflow Tool invocation path still appears to be affected.

Current source path that seems to explain the failure:

• api/core/plugin/entities/parameters.py: PluginParameterType.FILES casts any non-list value to [value], so an unset value such as None becomes [None].
• api/core/tools/workflow_as_tool/tool.py: WorkflowTool._transform_args() forwards normal FILES tool parameters into workflow inputs without normalizing optional empty placeholders.
• api/core/app/apps/base_app_generator.py: FILE_LIST validation accepts a list of file dicts or a list of File objects, but [None] fails validation and raises images in input form must be a list of files.

✔️ Expected Behavior

An optional file-list parameter for a Workflow Tool should be treated as an empty list when the selected upstream variable is unset or empty.

The parent workflow Tool node should be able to invoke the Workflow Tool successfully, and the child workflow should receive either images=[] or an equivalent empty optional file-list value.

❌ Actual Behavior

The parent workflow Tool node fails during tool invocation with:

images in input form must be a list of files

Because the Tool node UI only allows selecting a variable for the file-list parameter, there is no single-tool UI workaround to pass a literal empty array [] when no files are provided.