{"record":{"id":"15bd1e17fb4208c9","repo":"apache/seatunnel","slug":"the-gcs-bucket-must-be-a-bucket-uri-such-as-gs","errorCode":null,"errorMessage":"The GCS bucket must be a bucket URI such as 'gs://my-bucket', but was '%s'. Configure object paths with the 'path' option.","messagePattern":"The GCS bucket must be a bucket URI such as 'gs://my-bucket', but was '(.+?)'\\. Configure object paths with the 'path' option\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-gcs/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/gcs/config/GcsHadoopConf.java","lineNumber":70,"sourceCode":"\n        GcsHadoopConf hadoopConf = new GcsHadoopConf(bucket);\n        hadoopConf.setExtraOptions(properties);\n        return hadoopConf;\n    }\n\n    @Override\n    public String getFsHdfsImpl() {\n        return GCS_FILESYSTEM_IMPLEMENTATION;\n    }\n\n    @Override\n    public String getSchema() {\n        return SCHEMA;\n    }\n\n    private static void validateBucket(String bucket) {\n        if (StringUtils.isBlank(bucket)) {\n            throw invalidBucket(bucket);\n        }\n        try {\n            URI uri = new URI(bucket);\n            String path = uri.getPath();\n            if (!SCHEMA.equals(uri.getScheme())\n                    || StringUtils.isBlank(uri.getAuthority())\n                    || uri.getUserInfo() != null\n                    || uri.getPort() != -1\n                    || uri.getQuery() != null\n                    || uri.getFragment() != null\n                    || (StringUtils.isNotEmpty(path) && !\"/\".equals(path))) {\n                throw invalidBucket(bucket);\n            }\n        } catch (URISyntaxException e) {\n            throw invalidBucket(bucket);\n        }\n    }\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-gcs/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/gcs/config/GcsHadoopConf.java#L52-L88","documentation":"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.","triggerScenarios":"Calling buildWithReadonlyConfig with bucket = null, \"\", or whitespace; or bucket = 'gs://my-bucket' but with blank/missing authority such as 'gs://' or just 'my-bucket'.","commonSituations":"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.","solutions":["Set bucket to exactly 'gs://<bucket-name>' with no trailing path, query, or port","Move the object/prefix portion into the 'path' option","If bucket is coming from env/config, check it is non-blank before building GcsHadoopConf"],"exampleFix":"// before\nbucket = \"gs://my-bucket/logs/2026/*.json\"\n// after\nbucket = \"gs://my-bucket\"\npath = \"logs/2026\"","handlingStrategy":"validation","validationCode":"String bucket = config.get(\"bucket\");\nif (bucket == null || bucket.isBlank() || !bucket.matches(\"^gs://[^/]+/?$\"))\n    throw new IllegalArgumentException(\"bucket must be 'gs://<name>'; object paths go in 'path'\");","typeGuard":"static boolean isBucketUri(String bucket) {\n    return bucket != null && bucket.matches(\"^gs://[^/:?#[\\\\]]+/?$\");\n}","tryCatchPattern":"try {\n    GcsHadoopConf conf = GcsHadoopConf.buildWithReadonlyConfig(config, path);\n} catch (IllegalArgumentException e) {\n    // report the bucket option value and the expected format\n}","preventionTips":["Keep 'bucket' = 'gs://<name>' and put object/prefix in 'path'","Validate bucket format in config preprocessing before building GcsHadoopConf","Never embed credentials, ports, or queries in the bucket URI"],"tags":["gcs","config-validation","bucket"],"backgroundTag":"invalid-config-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}