Note: this is not designed to duplicate the exact checks that GCS would perform on the\n * server side. We make some checks that are relevant to using GCS as a file system.\n *\n * @param bucketName Bucket name to check.\n */\n static String validateBucketName(String bucketName) {\n // If the name ends with '/', remove it.\n bucketName = toFilePath(bucketName);\n\n if (isNullOrEmpty(bucketName)) {\n throw new IllegalArgumentException(\"GCS bucket name cannot be empty.\");\n }\n\n if (!BUCKET_NAME_CHAR_MATCHER.matchesAllOf(bucketName)) {\n throw new IllegalArgumentException(String.format(\n \"Invalid GCS bucket name '%s': bucket name must contain only 'a-z0-9_.-' characters.\",\n bucketName));\n }\n\n return bucketName;\n }\n\n /**\n * Validate the given object name to make sure that it can be used as a part of a file system\n * path.\n *\n *
Note: this is not designed to duplicate the exact checks that GCS would perform on the\n * server side. We make some checks that are relevant to using GCS as a file system.\n *\n * @param objectName Object name to check.\n * @param allowEmptyObjectName If true, a missing object name is not considered invalid.\n */\n static String validateObjectName(String objectName, boolean allowEmptyObjectName) {","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/StringPaths.java#L44-L80","documentation":"StringPaths.validateBucketName enforces GCS bucket naming relevant to filesystem use: the name (after trimming a trailing '/') must contain only characters a-z, 0-9, '_', '.', '-' (BUCKET_NAME_CHAR_MATCHER). Anything else - uppercase letters, spaces, slashes, unicode - throws IllegalArgumentException echoing the invalid name. This mirrors GCS server-side rules, caught client-side.","triggerScenarios":"fromUriPath with 'gs://MyBucket/key' (uppercase), a bucket containing '/', a space, or other disallowed characters; bucket names extracted from console URLs that include extra path segments.","commonSituations":"Legacy buckets with uppercase-style naming attempted from Hadoop; copy-paste from URLs like https://storage.googleapis.com/bucket/path where extra segments land in the authority; env-var interpolation injecting whitespace or slashes.","solutions":["Use bucket names containing only lowercase letters, digits, underscore, dot, hyphen (GCS requires this anyway at creation).","Strip anything after the first '/' when parsing bucket names out of URLs.","Validate bucket names with a regex before building gs:// URIs."],"exampleFix":"// before\nStorageResourceId.fromUriPath(URI.create(\"gs://MyBucket/key\"), false);\n// -> IllegalArgumentException: Invalid GCS bucket name 'MyBucket'\n\n// after\nString bucket = \"MyBucket\".toLowerCase(Locale.ROOT); // names must be [a-z0-9_.-]\nStorageResourceId.fromUriPath(URI.create(\"gs://\" + bucket + \"/key\"), false);","handlingStrategy":"validation","validationCode":"private static final Pattern GCS_BUCKET = Pattern.compile(\"^[a-z0-9_.-]+$\");\nstatic String checkedBucket(String b) {\n if (b == null || !GCS_BUCKET.matcher(b).matches()) {\n throw new IllegalArgumentException(\"Invalid GCS bucket name: \" + b);\n }\n return b;\n}","typeGuard":"static boolean isValidGcsBucketName(String b) {\n return b != null && b.matches(\"[a-z0-9_.-]+\");\n}","tryCatchPattern":"catch IllegalArgumentException with message startsWith(\"Invalid GCS bucket name\") - lowercase/strip the name and re-validate; if the bucket genuinely has invalid chars it cannot be used via the connector.","preventionTips":["Enforce [a-z0-9_.-] on bucket names at config-load time.","When copying bucket names out of console URLs, take only the authority component."],"tags":["gcs","bucket","validation","uri"],"backgroundTag":"invalid-bucket-name","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}