apache/dolphinscheduler · warning · FileAlreadyExistsException

directory: ${directory} already exists

Error message

directory: ${directory} already exists

What it means

OssStorageOperator.createStorageDir throws FileAlreadyExistsException when an object already exists at the transformed OSS key. OSS directories are zero-length placeholder objects, so an existing marker blocks re-creating the directory.

Source

Thrown at dolphinscheduler-storage-plugin/dolphinscheduler-storage-oss/src/main/java/org/apache/dolphinscheduler/plugin/storage/oss/OssStorageOperator.java:128

            log.warn("{} -> {} should not start with / in Oss", StorageConstants.RESOURCE_UPLOAD_PATH,
                    resourceBaseAbsolutePath);
            return resourceBaseAbsolutePath.substring(1);
        }
        return resourceBaseAbsolutePath;
    }

    @Override
    public void close() throws IOException {
        ossClient.shutdown();
    }

    @SneakyThrows
    @Override
    public void createStorageDir(String directory) {
        directory = transformAbsolutePathToOssKey(directory);

        if (ossClient.doesObjectExist(bucketName, directory)) {
            throw new FileAlreadyExistsException("directory: " + directory + " already exists");
        }
        ObjectMetadata metadata = new ObjectMetadata();
        metadata.setContentLength(0);
        InputStream emptyContent = new ByteArrayInputStream(new byte[0]);
        PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, directory, emptyContent, metadata);
        ossClient.putObject(putObjectRequest);
    }

    @SneakyThrows
    @Override
    public void download(String srcFilePath,
                         String dstFilePath,
                         boolean overwrite) {
        srcFilePath = transformAbsolutePathToOssKey(srcFilePath);

        File dstFile = new File(dstFilePath);
        if (dstFile.isDirectory()) {
            Files.delete(dstFile.toPath());

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check directory existence first (existsStorageDir) or delete the object before creating
2. Catch FileAlreadyExistsException and treat as no-op for idempotent scripts
3. Use unique directory names per execution

Example fix

// before
storageOperator.createStorageDir(dir);
// after
try {
    storageOperator.createStorageDir(dir);
} catch (FileAlreadyExistsException e) {
    // directory already present — safe to ignore
}

if (!storageOperator.existsStorageDir(directory)) {
    storageOperator.createStorageDir(directory);
}

try {
    storageOperator.createStorageDir(directory);
} catch (FileAlreadyExistsException e) {
    log.info("Directory {} already exists, ignoring", directory);
}

When it happens

Trigger: Calling createStorageDir(directory) when the OSS bucket already contains an object at transformAbsolutePathToOssKey(directory).

Common situations: Re-running a setup/workflow that creates the same resource directory; concurrent task instances creating the same directory; a file was uploaded to the same key previously.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• directory: ${directoryAbsolutePath} already exists
• file: ${dstPath} already exists
• The directory ${directoryAbsolutePath} already exists in the
• bucketName: <bucketName> is not exists, you need to create t
• file: ${dstPath} already exists

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