apache/dolphinscheduler · critical · IllegalArgumentException

bucketName: ${bucketName} is not exists, you need to create

Error message

bucketName: ${bucketName} is not exists, you need to create them by yourself

What it means

OssStorageOperator.ensureBucketSuccessfullyCreated throws IllegalArgumentException when doesBucketExist returns false for the configured bucket. OSS buckets must be pre-created; DolphinScheduler only verifies existence at init.

Source

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

        return storageEntityList;
    }

    @Override
    public StorageEntity getStorageEntity(String resourceAbsolutePath) {
        resourceAbsolutePath = transformAbsolutePathToOssKey(resourceAbsolutePath);
        OSSObject object = ossClient.getObject(new GetObjectRequest(bucketName, resourceAbsolutePath));
        return transformOSSObjectToStorageEntity(object);
    }

    private void ensureBucketSuccessfullyCreated(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException("resource.alibaba.cloud.oss.bucket.name is empty");
        }

        boolean existsBucket = ossClient.doesBucketExist(bucketName);
        if (!existsBucket) {
            throw new IllegalArgumentException(
                    "bucketName: " + bucketName + " is not exists, you need to create them by yourself");
        }

        log.info("bucketName: {} has been found, the current regionName is {}", bucketName, region);
    }
    protected StorageEntity transformOSSObjectToStorageEntity(OSSObject ossObject) {
        ResourceMetadata resourceMetaData = getResourceMetaData(ossObject.getKey());

        StorageEntity storageEntity = new StorageEntity();
        storageEntity.setFileName(new File(ossObject.getKey()).getName());
        storageEntity.setFullName(ossObject.getKey());
        storageEntity.setPfullName(resourceMetaData.getResourceParentAbsolutePath());
        storageEntity.setType(resourceMetaData.getResourceType());
        storageEntity.setDirectory(resourceMetaData.isDirectory());
        storageEntity.setSize(ossObject.getObjectMetadata().getContentLength());
        storageEntity.setRelativePath(resourceMetaData.getResourceRelativePath());
        storageEntity.setCreateTime(ossObject.getObjectMetadata().getLastModified());
        storageEntity.setUpdateTime(ossObject.getObjectMetadata().getLastModified());

View on GitHub (pinned to 02eac45a1b)

Solutions

Create the bucket in the OSS console in the region matching the configured endpoint
Correct the bucket name or endpoint in the config
Grant the RAM user oss:GetBucketInfo (list/read) permissions

Example fix

// before
resource.alibaba.cloud.oss.endpoint=oss-cn-beijing.aliyuncs.com
resource.alibaba.cloud.oss.bucket.name=bucket-in-shanghai
// after
resource.alibaba.cloud.oss.endpoint=oss-cn-shanghai.aliyuncs.com
resource.alibaba.cloud.oss.bucket.name=bucket-in-shanghai

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = new OSSClientBuilder().build(endpoint, ak, sk)
        .doesBucketExist(bucketName);
if (!ok) throw new IllegalStateException("OSS bucket " + bucketName + " not found at " + endpoint);

Try / catch

try {
    storageOperator = new OssStorageOperator(cfg);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is not exists")) {
        throw new IllegalStateException("Pre-create the OSS bucket or fix endpoint/permissions", e);
    }
    throw e;
}

Prevention

Create the bucket in the correct region before deployment
Match the endpoint to the bucket's region
Grant the RAM role oss:GetBucketInfo so existence checks succeed

When it happens

Trigger: Initializing OssStorageOperator with a bucket name that does not exist under the configured endpoint/credentials.

Common situations: Bucket created in a different region (endpoint mismatch); typo in bucket name; access key lacking OSS GetBucketInfo permission making existence checks fail; bucket removed after config was written.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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