apache/dolphinscheduler · error · ServiceException

Download the resource file

Error message

Download the resource file: {fileAbsolutePath} failed

What it means

ResourcesServiceImpl.downloadResource wraps any exception while streaming a resource file to the HTTP response into ServiceException("Download the resource file: <path> failed", e). It copies a local tmp file (previously fetched from storage) to the servlet output stream; failures reading the file, storage retrieval errors, or broken client connections surface here. The tmp file is deleted in finally regardless of outcome.

Solutions

  1. Check the wrapped cause in server logs: a missing storage object means the resource metadata is stale — re-upload or remove the resource entry.
  2. Verify storage connectivity and credentials from the API server, then retry the download.
  3. If the cause is a client disconnect (broken pipe), it is benign — retry the download from a stable connection.

Example fix

// before: stale resource entry pointing to deleted S3 object
GET /resources/download -> "Download the resource file: /wf/script.sql failed"

// after: re-upload the file via the resource center, then download succeeds
Defensive patterns

Strategy: try-catch

Validate before calling

// verify the resource exists in storage before downloading
// e.g. storageOperator.exists(resourceAbsolutePath) == true

Try / catch

try {
    resourcesService.downloadResource(response, request);
} catch (ServiceException e) {
    if (e.getCause() instanceof NoSuchFileException) {
        // re-upload or remove stale resource entry
    }
}

Prevention

When it happens

Trigger: Downloading a resource whose backing object is missing from HDFS/S3; local tmp write/read failure (disk full, permissions); client disconnects mid-copy causing IOException on the output stream.

Common situations: Storage object deleted externally or by retention policy while metadata row remains; browser canceled download causing broken-pipe; API server cannot reach storage cluster.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/ResourcesServiceImpl.java:380

                .build();
        downloadFileDtoValidator.validate(downloadFileDto);

        String fileName = new File(downloadFileDto.getFileAbsolutePath()).getName();
        String localTmpFileAbsolutePath = FileUtils.getDownloadFilename(fileName);

        try {
            storageOperator.download(downloadFileRequest.getFileAbsolutePath(), localTmpFileAbsolutePath, true);
            int length = (int) new File(localTmpFileAbsolutePath).length();
            ApiServerMetrics.recordApiResourceDownloadSize(length);

            response.reset();
            response.setContentType("application/octet-stream");
            response.setCharacterEncoding("utf-8");
            response.setContentLength(length);
            response.setHeader("Content-Disposition", "attachment;filename=" + fileName);
            Files.copy(Paths.get(localTmpFileAbsolutePath), response.getOutputStream());
        } catch (Exception e) {
            throw new ServiceException(
                    "Download the resource file: " + downloadFileRequest.getFileAbsolutePath() + " failed", e);
        } finally {
            FileUtils.deleteFile(localTmpFileAbsolutePath);
        }
    }

    @Override
    public StorageEntity queryFileStatus(String userName, String fileAbsolutePath) {
        return storageOperator.getStorageEntity(fileAbsolutePath);
    }

    @Override
    public String queryResourceBaseDir(User loginUser, ResourceType type) {

        User user = userDao.queryById(loginUser.getId());
        if (user == null) {
            throw new ServiceException(Status.USER_NOT_EXIST);
        }

View on GitHub (pinned to 02eac45a1b)