apache/dolphinscheduler · error · IllegalArgumentException

remote.logging.oss.bucket.name is empty

Error message

remote.logging.oss.bucket.name is empty

What it means

OssRemoteLogHandler.checkBucketNameExists validates OSS remote-log configuration before use. It throws IllegalArgumentException when the bucket name is blank, mirroring the message "remote.logging.oss.bucket.name is empty". The private check runs when the handler verifies the configured Alibaba Cloud OSS bucket exists.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/log/remote/OssRemoteLogHandler.java:98

        try {
            log.info("get remote log on OSS {} to {}", objectName, logPath);
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(logPath));
        } catch (Exception e) {
            log.error("error while getting remote log on OSS {} to {}", objectName, logPath, e);
        }
    }

    @Override
    public void close() throws IOException {
        if (ossClient != null) {
            ossClient.shutdown();
        }
    }

    private void checkBucketNameExists(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException(Constants.REMOTE_LOGGING_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", bucketName);
    }

    private String readOssAccessKeyId() {
        return PropertyUtils.getString(Constants.REMOTE_LOGGING_OSS_ACCESS_KEY_ID);
    }

    private String readOssAccessKeySecret() {
        return PropertyUtils.getString(Constants.REMOTE_LOGGING_OSS_ACCESS_KEY_SECRET);
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set remote.logging.oss.bucket.name=<your-bucket> in common.properties and restart the service
2. If the value is set but still blank at runtime, check for env-var substitution or templating failures that render it empty
3. Disable remote.logging.oss.enable if OSS remote logging is not intended
4. Pre-create the OSS bucket, because after the blank check the handler calls ossClient.doesBucketExist to verify existence

Example fix

// before (common.properties)
remote.logging.oss.enable=true
# remote.logging.oss.bucket.name not set

// after
remote.logging.oss.enable=true
remote.logging.oss.bucket.name=dolphinscheduler-logs
remote.logging.oss.endpoint=oss-cn-hangzhou.aliyuncs.com

String bucket = PropertyUtils.getString("remote.logging.oss.bucket.name");
if (bucket == null || bucket.trim().isEmpty()) {
    throw new IllegalStateException("remote.logging.oss.bucket.name must be set when remote.logging.oss.enable=true");
}

try {
    ossRemoteLogHandler.checkBucketNameExists(bucketName);
} catch (IllegalArgumentException e) {
    log.error("OSS remote logging config error: {}", e.getMessage());
}

When it happens

Trigger: checkBucketNameExists is invoked (during handler init/verification) with a null/empty/whitespace bucketName, i.e. remote.logging.oss.bucket.name is missing or empty in common.properties while OSS remote logging is enabled.

Common situations: Setting remote.logging.oss.enable=true without remote.logging.oss.bucket.name; copying an S3 config template and never adding the OSS-specific bucket key; config templating that renders an empty value for the bucket name.

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

• remote.logging.google.cloud.storage.bucket.name is blank
• bucketName: <bucketName> is not exists, you need to create t
• remote.logging.s3.bucket.name is blank
• The specified network interface: + specifiedNetworkInterface
• not support shell type:

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