apache/hadoop · error · IllegalArgumentException

Invalid GCS bucket name '%s': bucket name must contain only

Error message

Invalid GCS bucket name '%s': bucket name must contain only 'a-z0-9_.-' characters.

What it means

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.

Source

Thrown at hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/StringPaths.java:62

  /**
   * Validate the given bucket name to make sure that it can be used as a part of a file system
   * path.
   *
   * <p>Note: this is not designed to duplicate the exact checks that GCS would perform on the
   * server side. We make some checks that are relevant to using GCS as a file system.
   *
   * @param bucketName Bucket name to check.
   */
  static String validateBucketName(String bucketName) {
    // If the name ends with '/', remove it.
    bucketName = toFilePath(bucketName);

    if (isNullOrEmpty(bucketName)) {
      throw new IllegalArgumentException("GCS bucket name cannot be empty.");
    }

    if (!BUCKET_NAME_CHAR_MATCHER.matchesAllOf(bucketName)) {
      throw new IllegalArgumentException(String.format(
          "Invalid GCS bucket name '%s': bucket name must contain only 'a-z0-9_.-' characters.",
          bucketName));
    }

    return bucketName;
  }

  /**
   * Validate the given object name to make sure that it can be used as a part of a file system
   * path.
   *
   * <p>Note: this is not designed to duplicate the exact checks that GCS would perform on the
   * server side. We make some checks that are relevant to using GCS as a file system.
   *
   * @param objectName           Object name to check.
   * @param allowEmptyObjectName If true, a missing object name is not considered invalid.
   */
  static String validateObjectName(String objectName, boolean allowEmptyObjectName) {

View on GitHub (pinned to 2add963021)

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.

Example fix

// before
StorageResourceId.fromUriPath(URI.create("gs://MyBucket/key"), false);
// -> IllegalArgumentException: Invalid GCS bucket name 'MyBucket'

// after
String bucket = "MyBucket".toLowerCase(Locale.ROOT); // names must be [a-z0-9_.-]
StorageResourceId.fromUriPath(URI.create("gs://" + bucket + "/key"), false);

Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern GCS_BUCKET = Pattern.compile("^[a-z0-9_.-]+$");
static String checkedBucket(String b) {
  if (b == null || !GCS_BUCKET.matcher(b).matches()) {
    throw new IllegalArgumentException("Invalid GCS bucket name: " + b);
  }
  return b;
}

Type guard

static boolean isValidGcsBucketName(String b) {
  return b != null && b.matches("[a-z0-9_.-]+");
}

Try / catch

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.

Prevention

Enforce [a-z0-9_.-] on bucket names at config-load time.
When copying bucket names out of console URLs, take only the authority component.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/9d8358097ae5670d. Report an issue: GitHub.