Remote File Handling and Validation#

When a workflow input file is submitted with "transfer_method": "remote_url" and a bare URL (no pre-uploaded upload_file_id), the request flows through four stages: metadata probing, filename extraction, type resolution, and config validation. The relevant source files are:

Entry point is _build_from_remote_url() in builders.py.

Stage 1: Remote Metadata Probing#

get_remote_file_info(url) fires an SSRF-safe HTTP HEAD request via remote_fetcher.make_request("HEAD", url, follow_redirects=True). On HTTP 200, it reads:

• Content-Disposition → passed to extract_filename() (see next section)
• Content-Length → stored as file_size
• Content-Type → used as fallback MIME type if the filename extension doesn't resolve one

If no filename can be determined at all, a UUID-based fallback filename is generated using the guessed extension from the MIME type (e.g., <uuid>.jpeg). The function returns (mime_type, filename, file_size) 1.

Stage 2: Filename Extraction#

extract_filename(url_or_path, content_disposition) resolves a safe filename using the following priority chain:

1. RFC 5987 filename* — Regex-extracts the filename*=<charset>'<lang>'<pct-encoded-value> form, percent-decodes via urllib.parse.unquote(value, encoding=charset, errors="replace"). This was overhauled in PR #26230 to properly handle charset/language tags and prevent path injection.

2. Plain filename — Falls back to werkzeug's parse_options_header(), strips surrounding quotes, then percent-decodes 2.

3. URL path basename — When no Content-Disposition filename is available, uses urllib.parse.urlparse(url_or_path).path to isolate the URL path (discarding query strings and hash fragments), then decodes via urllib.parse.unquote(..., errors="replace"). This was fixed in PR #35706 to correctly handle presigned S3 URLs with X-Amz-* query parameters.

Security: The final result always passes through os.path.basename() to strip any path traversal sequences. Whitespace-only or empty results return None 3.

Stage 3: Type Resolution#

Back in _build_from_remote_url(), the resolved filename extension and MIME type are passed to standardize_file_type(extension, mime_type) to produce a FileType enum value 4.

_resolve_file_type() then reconciles the detected type with the caller-supplied type field:

• If no type is specified, the detected type wins.
• If type == "custom", FileType.CUSTOM is returned unconditionally — extension-whitelist enforcement is deferred to the config validation stage.
• If strict_type_validation=True and the detected type differs from the specified type, a ValueError is raised with the message "Detected file type does not match the specified type. Please verify the file." 5.

When is strict validation active? strict_type_validation=True is set when invoke_from == InvokeFrom.SERVICE_API, i.e., all Service API calls enforce strict type checking 6.

Stage 4: Config Validation#

After the File object is built, build_from_mapping() calls is_file_valid_with_config() if a FileUploadConfig is present. Validation logic:

1. Tool files bypass config — TOOL_FILE transfer method always returns True 7.
2. Type allowlist — input_file_type must be in config.allowed_file_types, or CUSTOM must be in that list 8.
3. Extension whitelist (CUSTOM bucket) — When the file falls into the CUSTOM bucket (either explicitly typed as CUSTOM or when its type isn't in the allowlist), config.allowed_file_extensions is enforced. An explicitly empty list means deny all 9. Extension matching is case- and dot-insensitive via _normalize_extension() 10.
4. Transfer method check — IMAGE files check image_config.transfer_methods; all others check allowed_file_upload_methods 11.

Common Error: "Detected file type does not match the specified type"#

This error requires all three conditions to hold simultaneously 6:

1. Service API invocation (strict_type_validation=True)
2. Non-null type field in the input mapping (note: "custom" is a common default)
3. Type mismatch — the extension/MIME-derived FileType differs from the specified type

Fixes and workarounds:

• Pass a type value that matches the file's actual extension (e.g., "document" for .txt, .pdf, .docx) 12.
• Upload via /files/upload first to obtain an upload_file_id, then reference it with transfer_method: "local_file" — this avoids live URL probing entirely.
• For presigned S3 URLs, ensure the URL path contains a file extension (e.g., ends in .jpg) because Dify's filename extraction depends on it when Content-Disposition is absent.
• The "custom" type only avoids strict-type errors if the workflow's variable is also configured as CUSTOM; otherwise the CUSTOM extension whitelist applies.