apache/dolphinscheduler · error · IllegalArgumentException

resource.alibaba.cloud.google.storage.bucket.name is blank

Error message

resource.alibaba.cloud.google.storage.bucket.name is blank

What it means

GcsStorageOperator.checkBucketNameExists validates the configured GCS bucket name at startup. If the resource config key resource.alibaba.cloud.google.storage.bucket.name is blank/empty it throws IllegalArgumentException immediately, since no storage operations can work without a bucket.

Source

Thrown at dolphinscheduler-storage-plugin/dolphinscheduler-storage-gcs/src/main/java/org/apache/dolphinscheduler/plugin/storage/gcs/GcsStorageOperator.java:246

                    }
                    foldersToFetch.add(temp.getFullName());
                }
            }
            storageEntityList.addAll(tempList);
        }
        return storageEntityList;
    }

    @Override
    public StorageEntity getStorageEntity(String resourceAbsolutePath) {
        resourceAbsolutePath = transformAbsolutePathToGcsKey(resourceAbsolutePath);
        Blob blob = gcsStorage.get(BlobId.of(bucketName, resourceAbsolutePath));
        return transformBlobToStorageEntity(blob);
    }

    private void checkBucketNameExists(String bucketName) {
        if (StringUtils.isBlank(bucketName)) {
            throw new IllegalArgumentException(StorageConstants.GOOGLE_CLOUD_STORAGE_BUCKET_NAME + " is blank");
        }

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

        if (!exist) {
            throw new IllegalArgumentException(
                    "bucketName: " + bucketName + " is not exists, you need to create them by yourself");
        } else {
            log.info("bucketName: {} has been found", bucketName);
        }
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set resource.alibaba.cloud.google.storage.bucket.name in the storage config (common.properties / application.yaml)
2. Verify the property key spelling matches StorageConstants.GOOGLE_CLOUD_STORAGE_BUCKET_NAME
3. Restart the service after editing configuration so the operator re-initializes

Example fix

// before (common.properties)
# resource.alibaba.cloud.google.storage.bucket.name=
// after
resource.alibaba.cloud.google.storage.bucket.name=my-gcs-bucket

String bucket = config.get("resource.alibaba.cloud.google.storage.bucket.name");
if (bucket == null || bucket.isBlank()) throw new IllegalStateException("GCS bucket name must be configured");

try {
    new GcsStorageOperator(...);
} catch (IllegalArgumentException e) {
    log.error("GCS storage misconfigured: {}", e.getMessage());
}

When it happens

Trigger: Initializing GcsStorageOperator when StorageConstants.GOOGLE_CLOUD_STORAGE_BUCKET_NAME (resource.alibaba.cloud.google.storage.bucket.name) is missing or set to an empty/whitespace value in the storage configuration.

Common situations: Switching storage type to GCS without adding the bucket-name property; typos in the property name; config file not picked up so the default empty value is used.

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
• remote.logging.google.cloud.storage.bucket.name is blank
• receivers must not be null
• url can not be null
• headerParams is not a valid json

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