apache/dolphinscheduler · error · IllegalArgumentException

remote.logging.s3.bucket.name is blank

Error message

remote.logging.s3.bucket.name is blank

What it means

S3RemoteLogHandler.checkBucketNameExists validates S3 remote-log configuration. It throws IllegalArgumentException with the literal message "remote.logging.s3.bucket.name is blank" when the bucket name passed in is null/empty/whitespace. This fail-fast check runs before s3Client.doesBucketExistV2 is called.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/log/remote/S3RemoteLogHandler.java:110

                    FileOutputStream fos = new FileOutputStream(logPath)) {
                byte[] readBuf = new byte[1024];
                int readLen = 0;
                while ((readLen = s3is.read(readBuf)) > 0) {
                    fos.write(readBuf, 0, readLen);
                }
            }
        } catch (Exception e) {
            log.error("error while getting remote log on S3 {} to {}", objectName, logPath, e);
        }
    }

    protected String readBucketName() {
        return PropertyUtils.getString(Constants.AWS_S3_BUCKET_NAME);
    }

    public void checkBucketNameExists(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException("remote.logging.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());
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set remote.logging.s3.bucket.name=<your-bucket> in common.properties and restart
2. Confirm you are using the correct property key remote.logging.s3.bucket.name (not aws.s3.bucket.name or similar) since PropertyUtils returns null for unknown keys
3. Disable remote.logging.s3.enable if S3 remote logging is not needed
4. Ensure the value has no surrounding quotes-only or whitespace content that parses as blank

Example fix

// before (common.properties)
remote.logging.s3.enable=true

// after
remote.logging.s3.enable=true
remote.logging.s3.bucket.name=dolphinscheduler-logs
remote.logging.s3.region=us-east-1

String bucket = PropertyUtils.getString("remote.logging.s3.bucket.name");
if (bucket == null || bucket.trim().isEmpty()) {
    throw new IllegalStateException("Set remote.logging.s3.bucket.name in common.properties before enabling S3 remote logging");
}

try {
    s3RemoteLogHandler.checkBucketNameExists(bucketName);
} catch (IllegalArgumentException e) {
    log.error("S3 remote logging misconfigured: {}", e.getMessage());
}

When it happens

Trigger: checkBucketNameExists is called during handler initialization with a blank bucketName because PropertyUtils.getString(Constants.AWS_S3_BUCKET_NAME) returned null/empty, i.e. remote.logging.s3.bucket.name is unset in common.properties while S3 remote logging is enabled.

Common situations: Setting remote.logging.s3.enable=true without the bucket name; AWS configuration migrated to another key (note readBucketName uses AWS_S3_BUCKET_NAME, not a GCS-style key, so a wrong key name yields null); environment-specific config files that omit S3 keys.

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

• bucketName: <bucketName> is not exists, you need to create t
• bucketName: ${bucketName} is not exists, you need to create
• remote.logging.google.cloud.storage.bucket.name is blank
• remote.logging.oss.bucket.name is empty
• resource.aws.s3.bucket.name is blank

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