Workflow File Handling#

Overview#

Workflow file handling in Dify converts raw file payload dictionaries (called mappings) into graphon.File objects that flow through the variable pool between nodes. The entire subsystem lives under api/factories/file_factory/. The two public entry points are:

• build_from_mapping() — builds a single File from one mapping dict
• build_from_mappings() — builds a sequence of File objects, enforcing FileUploadConfig count limits

Both require a tenant_id, a FileAccessControllerProtocol (for tenancy-scoped DB queries), and an optional FileUploadConfig.

The graphon.File Model#

File is defined in the external graphon package (not in the dify repo) and imported as from graphon.file import File, FileTransferMethod, FileType, FileUploadConfig 1. Key fields constructed by the factory:

Transfer Methods#

build_from_mapping() dispatches on transfer_method to one of four private builders 2:

1. local_file — _build_from_local_file()#

Looks up an UploadFile DB row by upload_file_id (with fallback to reference / related_id via resolve_mapping_file_id()). Enforces UploadFile.tenant_id == tenant_id 3. Returns a File with remote_url set to a signed URL via helpers.get_signed_file_url() 4.

2. remote_url — _build_from_remote_url()#

Two sub-paths:

• Pre-uploaded: if upload_file_id is present, resolves an UploadFile row (same as local_file, but emits a signed URL).
• Bare URL: calls get_remote_file_info(url) to HTTP HEAD-probe the URL for MIME type, filename, and file size, then constructs the File with remote_url set to the external URL and no reference or storage_key. See Remote File Handling and Validation for the full probing pipeline.

3. tool_file — _build_from_tool_file()#

Resolves a ToolFile DB row by tool_file_id. Extension is derived from filename, then MIME type, then the file's storage key 5. Tool files bypass upload config validation entirely (see Config Validation below).

4. datasource_file — _build_from_datasource_file()#

Resolves an UploadFile row by datasource_file_id. Extension is derived from the storage key suffix 6. Sets both remote_url and url from source_url.

Type Resolution#

After DB/remote lookup, every builder calls _resolve_file_type() which reconciles:

• The FileType detected from extension+MIME via standardize_file_type()
• The caller-supplied type field in the mapping

Rules 7:

• No type specified → detected type wins
• type == "custom" → FileType.CUSTOM always (extension enforcement deferred to config validation)
• strict_type_validation=True and types differ → ValueError("Detected file type does not match the specified type.")

strict_type_validation is True for Service API calls (invoke_from == InvokeFrom.SERVICE_API).

File Reference Format#

Persisted files (local, tool, datasource) get a reference field containing an opaque dify-file-ref:<base64url-json> string built by build_file_reference(). The JSON payload contains record_id (the DB UUID) and optionally storage_key. This format is required by new agent-v2 output contracts; legacy raw record IDs are still readable via the permissive parse_file_reference() helper.

Config Validation#

After the File is built, build_from_mapping() calls is_file_valid_with_config() if a FileUploadConfig is provided. Checks (in order):

1. TOOL_FILE transfer method → always valid 8
2. input_file_type must be in config.allowed_file_types (or CUSTOM must be in the list) 9
3. For CUSTOM-bucket files: config.allowed_file_extensions whitelist is enforced (empty list = deny all) 10
4. Transfer method must be in image_config.transfer_methods (images) or config.allowed_file_upload_methods (others) 11

build_from_mappings() additionally enforces config.image_config.number_limits and config.number_limits across the full set 12.

Mapping TypedDicts#

The factory defines four typed mapping shapes 13:

All support reference (priority 2) and related_id (priority 3, legacy) as fallback ID fields. An id field, if present, maps directly to File.file_id (the graph-layer identity, not the DB record ID).

Callers#