apache/seatunnel · error · IllegalArgumentException

The GCS bucket must be a bucket URI such as…

Error message

The GCS bucket must be a bucket URI such as 'gs://my-bucket', but was '%s'. Configure object paths with the 'path' option.

What it means

GcsHadoopConf.validateBucket enforces that the 'bucket' option is exactly a bucket URI: scheme 'gs', non-blank authority, no user info, port, query, fragment, and no path beyond '/'. Object-level paths must go in the 'path' option instead. Blank input triggers the same IllegalArgumentException immediately.

Solutions

1. Set bucket to exactly 'gs://<bucket-name>' with no trailing path, query, or port
2. Move the object/prefix portion into the 'path' option
3. If bucket is coming from env/config, check it is non-blank before building GcsHadoopConf

Example fix

// before
bucket = "gs://my-bucket/logs/2026/*.json"
// after
bucket = "gs://my-bucket"
path = "logs/2026"

String bucket = config.get("bucket");
if (bucket == null || bucket.isBlank() || !bucket.matches("^gs://[^/]+/?$"))
    throw new IllegalArgumentException("bucket must be 'gs://<name>'; object paths go in 'path'");

static boolean isBucketUri(String bucket) {
    return bucket != null && bucket.matches("^gs://[^/:?#[\\]]+/?$");
}

try {
    GcsHadoopConf conf = GcsHadoopConf.buildWithReadonlyConfig(config, path);
} catch (IllegalArgumentException e) {
    // report the bucket option value and the expected format
}

When it happens

Trigger: Calling buildWithReadonlyConfig with bucket = null, "", or whitespace; or bucket = 'gs://my-bucket' but with blank/missing authority such as 'gs://' or just 'my-bucket'.

Common situations: Users paste a full object path (gs://bucket/dir/file.json) into the bucket option, or set bucket without the gs:// scheme, or leave bucket empty when copying a template config.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• All candidate sink tables were skipped during job parsing.
• AmazonDocumentDB option 'uri' must include authentication…
• batch_size must be >= 1, got:
• Binary chunk size must be positive, got
• Binary chunk size too large (max 100MB), got

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/15bd1e17fb4208c9. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-gcs/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/gcs/config/GcsHadoopConf.java:70

        GcsHadoopConf hadoopConf = new GcsHadoopConf(bucket);
        hadoopConf.setExtraOptions(properties);
        return hadoopConf;
    }

    @Override
    public String getFsHdfsImpl() {
        return GCS_FILESYSTEM_IMPLEMENTATION;
    }

    @Override
    public String getSchema() {
        return SCHEMA;
    }

    private static void validateBucket(String bucket) {
        if (StringUtils.isBlank(bucket)) {
            throw invalidBucket(bucket);
        }
        try {
            URI uri = new URI(bucket);
            String path = uri.getPath();
            if (!SCHEMA.equals(uri.getScheme())
                    || StringUtils.isBlank(uri.getAuthority())
                    || uri.getUserInfo() != null
                    || uri.getPort() != -1
                    || uri.getQuery() != null
                    || uri.getFragment() != null
                    || (StringUtils.isNotEmpty(path) && !"/".equals(path))) {
                throw invalidBucket(bucket);
            }
        } catch (URISyntaxException e) {
            throw invalidBucket(bucket);
        }
    }

View on GitHub (pinned to cf67b549a7)