File Upload Configuration#

Overview#

File upload size limits and batch counts in Dify flow through three tightly linked layers:

1. Backend config (FileUploadConfig class) — the authoritative source of all limits, set via environment variables.
2. API endpoint (GET /console/api/files/upload) — reads those values and exposes them as a JSON config object.
3. Frontend hook (useFileSizeLimit) — consumes the API response and applies per-type size checks before upload.

1. Backend: FileUploadConfig#

All limits are declared in the FileUploadConfig class inside api/configs/feature/__init__.py. This class is a Pydantic BaseSettings mixin composed into the main FeatureConfig object, so every value can be overridden via environment variable.

1

Package Archive Validation Limits#

These limits control the validation of .ifpkg archives during skill and agent package operations. They are enforced by SkillPackageService during skill package import/validation and by RosterPackageExporter during Roster Agent export. These bounds are separate from the standard file upload size limits and apply to archive structure and nested content.

A computed field UPLOAD_FILE_EXTENSION_BLACKLIST parses the UPLOAD_FILE_EXTENSION_BLACKLIST env var (comma-separated, e.g. exe,bat,sh) into a set of lowercase extensions. By default the set is empty (all types allowed).

Canonical defaults are also shown in api/.env.example.

2. API: Config Exposure Endpoint#

GET /console/api/files/upload returns all current limits as a JSON payload. The handler reads directly from dify_config 2:

file_size_limit, knowledge_file_size_limit, batch_count_limit, file_upload_limit, image_file_size_limit, video_file_size_limit, audio_file_size_limit, skill_file_size_limit, workflow_file_upload_limit, image_file_batch_limit, single_chunk_attachment_limit, attachment_image_file_size_limit

The response schema is the UploadConfig Pydantic model from api/fields/file_fields.py.

knowledge_file_size_limit (int): Maximum file size in megabytes for knowledge base uploads for the current tenant. On paid plans (Professional, Team), this may be higher than file_size_limit. This value is determined by the tenant's subscription plan and the KNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN configuration.

POST /console/api/files/upload uploads a file. The controller calls FileService.upload_file, which enforces size limits and raises FileTooLargeError, UnsupportedFileTypeError, or BlockedFileExtensionError on validation failures.

When uploading files with source=datasets (knowledge base uploads), the system calls FeatureService.get_knowledge_file_size_limit(), which returns the larger of UPLOAD_FILE_SIZE_LIMIT and KNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN for paid plans (Professional, Team), or just UPLOAD_FILE_SIZE_LIMIT for free/sandbox plans. This limit is passed to FileService.upload_file as default_file_size_limit and applies to non-media file types (documents).

3. Frontend: useFileSizeLimit Hook#

The frontend fetches the config object from the API and stores it as FileUploadConfigResponse 3. The useFileSizeLimit hook in web/app/components/base/file-uploader/hooks.ts converts the MB values to bytes and falls back to hardcoded constants if the config is unavailable:

Fallback constants are defined in web/app/components/base/file-uploader/constants.ts.

The checkSizeLimit callback (returned by useFile) dispatches on SupportUploadFileTypes (image / document / audio / video / custom) and shows a toast error if the file exceeds the applicable limit, blocking the upload. This check runs for both local file picks and remote URL pastes 4.

Data Flow Diagram#

env vars
  └─► FileUploadConfig (api/configs/feature/__init__.py)
        └─► dify_config.UPLOAD_*
              └─► GET /console/api/files/upload
                    └─► FileUploadConfigResponse (web/models/common.ts)
                          └─► useFileSizeLimit() → checkSizeLimit()
                                └─► toast error / block upload

Key Source Files#