apache/dolphinscheduler · error · IllegalArgumentException

remote.logging.google.cloud.storage.bucket.name is blank

Error message

remote.logging.google.cloud.storage.bucket.name is blank

What it means

GcsRemoteLogHandler.checkBucketNameExists validates that remote logging to Google Cloud Storage is properly configured. It throws IllegalArgumentException when the configured bucket name (remote.logging.google.cloud.storage.bucket.name) is blank, before attempting to list buckets. This fail-fast check prevents the handler from silently failing to upload task logs to GCS.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/log/remote/GcsRemoteLogHandler.java:130

    protected Storage buildGcsStorage(String credential) throws IOException {
        return StorageOptions.newBuilder()
                .setCredentials(ServiceAccountCredentials.fromStream(
                        Files.newInputStream(Paths.get(credential))))
                .build()
                .getService();
    }

    protected String readCredentials() {
        return PropertyUtils.getString(Constants.REMOTE_LOGGING_GCS_CREDENTIAL);
    }

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

    public void checkBucketNameExists(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException(Constants.REMOTE_LOGGING_GCS_BUCKET_NAME + " is blank");
        }

        boolean exist = false;
        for (Bucket bucket : gcsStorage.list().iterateAll()) {
            if (bucketName.equals(bucket.getName())) {
                exist = true;
                break;
            }
        }

        if (!exist) {
            log.error(
                    "bucketName: {} does not exist, you need to create them by yourself", bucketName);
        } else {
            log.info("bucketName: {} has been found", bucketName);
        }
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set remote.logging.google.cloud.storage.bucket.name=<your-bucket> in dolphinscheduler-common/src/main/resources/common.properties (or the deployed conf dir) and restart
2. Verify the property is actually loaded: check the deployed common.properties, not just the repo copy, and confirm no leading/trailing quotes or whitespace-only value
3. If remote logging is not needed, disable remote.logging.gcs.enable so the GCS handler is never initialized
4. Confirm the bucket exists in GCS beforehand, since after the blank check the handler lists buckets to verify the name matches one you control

Example fix

// before (common.properties)
remote.logging.gcs.enable=true
remote.logging.google.cloud.storage.bucket.name=

// after
remote.logging.gcs.enable=true
remote.logging.google.cloud.storage.bucket.name=my-dolphinscheduler-logs

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

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

When it happens

Trigger: Calling checkBucketNameExists(String bucketName) with a null, empty, or whitespace-only bucketName; this happens at handler initialization when PropertyUtils.getString(Constants.REMOTE_LOGGING_GCS_BUCKET_NAME) returns blank because remote.logging.google.cloud.storage.bucket.name is unset or empty in common.properties.

Common situations: Enabling remote.logging.gcs.enable=true in common.properties but forgetting to set remote.logging.google.cloud.storage.bucket.name; leaving the property as an empty placeholder value; deploying with a stale/partial config that omits GCS 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

• remote.logging.oss.bucket.name is empty
• remote.logging.s3.bucket.name is blank
• The specified network interface: + specifiedNetworkInterface
• resource.alibaba.cloud.google.storage.bucket.name is blank
• bucketName: ${bucketName} is not exists, you need to create

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