apache/dolphinscheduler · error · IllegalArgumentException

resource.aws.s3.bucket.name is blank

Error message

resource.aws.s3.bucket.name is blank

What it means

exceptionWhenBucketNameNotExists throws IllegalArgumentException when the configured S3 bucket name (resource.aws.s3.bucket.name) is blank/null. The operator cannot target any bucket without a name, so startup/configuration validation fails fast before any S3 call.

Source

Thrown at dolphinscheduler-storage-plugin/dolphinscheduler-storage-s3/src/main/java/org/apache/dolphinscheduler/plugin/storage/s3/S3StorageOperator.java:211

    @SneakyThrows
    @Override
    public List<String> fetchFileContent(String filePath, int skipLineNums, int limit) {
        filePath = transformAbsolutePathToS3Key(filePath);
        S3Object s3Object = s3Client.getObject(bucketName, filePath);
        try (
                InputStreamReader inputStreamReader = new InputStreamReader(s3Object.getObjectContent());
                BufferedReader bufferedReader = new BufferedReader(inputStreamReader)) {
            return bufferedReader.lines()
                    .skip(skipLineNums)
                    .limit(limit)
                    .collect(Collectors.toList());
        }
    }

    void exceptionWhenBucketNameNotExists(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException("resource.aws.s3.bucket.name is blank");
        }

        boolean existsBucket = s3Client.doesBucketExistV2(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,
                s3Client.getRegionName());
    }

    @Override
    public List<StorageEntity> listStorageEntity(String resourceAbsolutePath) {
        final String s3ResourceAbsolutePath = transformAbsolutePathToS3Key(resourceAbsolutePath);
        ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request()
                .withBucketName(bucketName)
                .withDelimiter("/")

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set resource.aws.s3.bucket.name in common.properties to an existing bucket name
2. If injecting via env vars, verify the substitution produces a non-empty value
3. Restart/verify configuration loading after the change

Example fix

# before
resource.aws.s3.bucket.name=
# after
resource.aws.s3.bucket.name=my-dolphinscheduler-bucket

String bucket = conf.get("resource.aws.s3.bucket.name");
if (bucket == null || bucket.trim().isEmpty()) {
    throw new IllegalArgumentException("resource.aws.s3.bucket.name must be set before starting with S3 storage");
}

try {
    storageOperator.init();
} catch (IllegalArgumentException e) {
    log.error("S3 configuration invalid: {}", e.getMessage()); // fix common.properties
}

When it happens

Trigger: Constructing S3StorageOperator (or calling exceptionWhenBucketNameNotExists) with an empty or whitespace-only bucket name, i.e. resource.aws.s3.bucket.name is unset or empty in common.properties.

Common situations: Fresh installs where the S3 resource storage section was left with defaults; environment-variable substitution failing so the value renders empty; users switching resource storage to S3 without editing the config.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• url can not be null
• remote.logging.s3.bucket.name is blank
• bucketName: <bucketName> is not exists, you need to create t
• bucketName: ${bucketName} is not exists, you need to create
• sell task params is not valid

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