apache/dolphinscheduler · error · IllegalArgumentException

bucketName: ${bucketName} is not exists, you need to create

Error message

bucketName: ${bucketName} is not exists, you need to create them by yourself

What it means

After confirming the bucket name is non-blank, GcsStorageOperator.checkBucketNameExists lists the project's buckets and throws IllegalArgumentException if none matches the configured name. This fails fast so storage errors surface at startup instead of during resource operations.

Source

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

        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);
        }
    }

    private StorageEntity transformBlobToStorageEntity(Blob blob) {
        String absolutePath = transformGcsKeyToAbsolutePath(blob.getName());

        ResourceMetadata resourceMetaData = getResourceMetaData(absolutePath);

        StorageEntity entity = new StorageEntity();
        entity.setFileName(new File(absolutePath).getName());
        entity.setFullName(absolutePath);
        entity.setDirectory(resourceMetaData.isDirectory());
        entity.setType(resourceMetaData.getResourceType());
        entity.setSize(blob.getSize());
        entity.setRelativePath(resourceMetaData.getResourceRelativePath());

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Create the bucket in the GCP project: gsutil mb gs://<bucket-name> or via Cloud Console
  2. Correct the configured bucket name to match an existing bucket
  3. Check the service account credentials/project and grant permission to list buckets

Example fix

// before
resource.alibaba.cloud.google.storage.bucket.name=my-bukcet
// after
resource.alibaba.cloud.google.storage.bucket.name=my-bucket  # must exist in the project
Defensive patterns

Strategy: validation

Validate before calling

try (Storage s = StorageOptions.getDefaultInstance().getService()) {
    boolean found = Iterables.contains(
        Iterables.transform(s.list().iterateAll(), Bucket::getName), bucketName);
    if (!found) throw new IllegalStateException("Bucket missing: " + bucketName);
}

Try / catch

try {
    new GcsStorageOperator(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is not exists")) {
        log.error("Create bucket first: gsutil mb gs://{}", configuredBucket);
    }
}

Prevention

When it happens

Trigger: Initializing GcsStorageOperator when gcsStorage.list().iterateAll() contains no bucket whose name equals the configured resource.alibaba.cloud.google.storage.bucket.name — the bucket was never created or belongs to another project/credentials.

Common situations: Typo in the bucket name; bucket created in a different GCP project than the service account's; credentials lacking resourcemanager/projects.get / storage.buckets.list permission; bucket deleted.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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