What causes "GCS bucket name cannot be empty." in apache/hadoop?

Always include the bucket as the URI authority: gs:// / .

apache/hadoop · error · IllegalArgumentException

GCS bucket name cannot be empty.

Error message

GCS bucket name cannot be empty.

What it means

StringPaths.validateBucketName (reached via StorageResourceId.fromUriPath) rejects an empty bucket name: after stripping any trailing '/', the authority must be non-empty. This means the supplied gs URI has no bucket - e.g. 'gs://', 'gs:/path', or 'gs:///key'.

Source

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

      .and(CharMatcher.inRange('0', '9').or(CharMatcher.inRange('a', 'z'))
          .or(CharMatcher.anyOf("_.-")))
      .precomputed();

  /**
   * 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.
   *

View on GitHub (pinned to 2add963021)

Solutions

Always include the bucket as the URI authority: gs://<bucket>/<object>.
Validate that the bucket variable/config is non-empty before constructing the URI.
Where input is untrusted, fail fast with your own message naming the missing bucket.

Example fix

// before
URI uri = URI.create(String.format("gs://%s/%s", bucket, object)); // bucket == "" -> 'gs:///object'
StorageResourceId.fromUriPath(uri, false); // IllegalArgumentException

// after
checkArgument(!bucket.isEmpty(), "bucket must be set");
URI uri = URI.create(String.format("gs://%s/%s", bucket, object));

Defensive patterns

Strategy: validation

Validate before calling

String bucket = requiredBucket(); // from config
if (bucket == null || bucket.isEmpty()) {
  throw new IllegalArgumentException("GCS bucket config is missing");
}
URI uri = URI.create("gs://" + bucket + "/" + object);

Type guard

static boolean hasGcsBucket(URI u) {
  String a = u.getAuthority();
  return a != null && !a.isEmpty();
}

Try / catch

catch IllegalArgumentException with message equals("GCS bucket name cannot be empty.") - the URI lacks an authority; rebuild it as gs://<bucket>/<object> before retrying.

Prevention

Always format gs URIs as gs://bucket/object with a validated non-empty bucket.
Fail fast on empty bucket config at startup rather than deep in FS calls.

When it happens

Trigger: fromUriPath on a URI whose authority is null/empty: 'gs:///object', 'gs://', or a URI built with String.format where the bucket variable was null or empty.

Common situations: Building gs:// URIs by string concatenation with an unset bucket config/variable; paths from configs missing the authority; URI parsing that drops the authority component (e.g. resolve() edge cases).

Related errors

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