What causes "The file is null" in apache/dolphinscheduler?

Attach the file under the form field name the endpoint expects (typically 'file').

apache/dolphinscheduler · error · ServiceException

The file is null

Error message

The file is null

What it means

exceptionFileInvalidated rejects a null MultipartFile with ServiceException("The file is null"). It is called by resource upload/create endpoints to ensure a file attachment was actually provided before storage operations are attempted.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/validator/resource/AbstractResourceValidator.java:70

        this.storageOperator = storageOperator;
        this.tenantDao = tenantDao;
    }

    public void exceptionResourceAbsolutePathInvalidated(String resourceAbsolutePath) {
        if (StringUtils.isBlank(resourceAbsolutePath)) {
            throw new ServiceException("The resource path is null");
        }
        if (!resourceAbsolutePath.startsWith(storageOperator.getStorageBaseDirectory())) {
            throw new ServiceException("Invalidated resource path: " + resourceAbsolutePath);
        }
        if (resourceAbsolutePath.contains("..")) {
            throw new ServiceException("Invalidated resource path: " + resourceAbsolutePath);
        }
    }

    public void exceptionFileInvalidated(MultipartFile file) {
        if (file == null) {
            throw new ServiceException("The file is null");
        }
    }

    public void exceptionFileContentInvalidated(String fileContent) {
        if (StringUtils.isEmpty(fileContent)) {
            throw new ServiceException("The file content is null");
        }
    }

    public void exceptionFileContentCannotFetch(String fileAbsolutePath) {
        String fileExtension = Files.getFileExtension(fileAbsolutePath);
        if (!FILE_SUFFIXES_WHICH_CAN_FETCH_CONTENT.contains(fileExtension)) {
            throw new ServiceException("The file type: " + fileExtension + " cannot be fetched");
        }
    }

    public void exceptionResourceNotExists(String resourceAbsolutePath) {
        if (!storageOperator.exists(resourceAbsolutePath)) {

View on GitHub (pinned to 02eac45a1b)

Solutions

Attach the file under the form field name the endpoint expects (typically 'file').
Ensure the request Content-Type is multipart/form-data and the client includes the file part.
Check multipart max-file-size/max-request-size settings if the part is being dropped server-side.

Example fix

// before
curl -X POST .../resources -H 'token: ...'      # no file part
// after
curl -X POST .../resources -H 'token: ...' -F 'file=@script.sql' -F 'type=FILE'

Defensive patterns

Strategy: validation

Validate before calling

// client-side pre-check (browser FormData)
if (!formData.has('file') || !formData.get('file').name) {
    throw new Error("A file must be attached under the 'file' form field");
}

Type guard

function hasFilePart(req) {
  return req.file != null && typeof req.file.originalname === 'string' && req.file.size > 0;
}

Try / catch

try {
    // upload resource
} catch (ServiceException e) {
    if (e.getMessage().equals("The file is null")) {
        // fix the multipart request and retry
    } else throw e;
}

Prevention

Use -F 'file=@path' with curl and the exact expected form-field name
Set enctype="multipart/form-data" on upload forms
Verify servlet multipart limits (max-file-size) are not silently dropping the part

When it happens

Trigger: POSTing to resource upload endpoints without a multipart file part, or with a part whose name does not match what the controller binds (so the MultipartFile binds as null).

Common situations: curl/script uploads missing -F file=@... or using the wrong form-field name; frontend forms not setting enctype=multipart/form-data; request size filter silently dropping the file part.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/0544166f1ed0a6de. Report an issue: GitHub.