apache/hadoop · error · IllegalArgumentException

Invalid bucket name (%s) or object name (%s)

Error message

Invalid bucket name (%s) or object name (%s)

What it means

UriPaths (hadoop-gcp) rebuilds a gs:// URI via new URI("gs", authority, path, null, null) after validateBucketName/validateObjectName succeed. If the bucket or object name contains characters java.net.URI does not accept in the authority/path components (spaces, '{', '|', non-ASCII, '%', etc.), URISyntaxException is raised and rethrown as IllegalArgumentException('Invalid bucket name (%s) or object name (%s)') with the original cause attached. The message shows the offending raw values, so inspect them for illegal characters.

Source

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

  /**
   * Constructs and returns full path for the given bucket and object names.
   */
  public static URI fromStringPathComponents(String bucketName, String objectName,
      boolean allowEmptyObjectName) {
    if (allowEmptyObjectName && bucketName == null && objectName == null) {
      return GoogleCloudStorageFileSystem.GCSROOT;
    }

    String authority = StringPaths.validateBucketName(bucketName);
    String path = PATH_DELIMITER + StringPaths.validateObjectName(objectName, allowEmptyObjectName);

    try {
      return new URI(SCHEME, authority, path,
          /* query= */ null,
          /* fragment= */ null);
    } catch (URISyntaxException e) {
      throw new IllegalArgumentException(
          String.format("Invalid bucket name (%s) or object name (%s)", bucketName, objectName), e);
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Percent-encode the object name per RFC 3986 before constructing the URI (encode each path segment, keep '/' separators).
2. Sanitize file names at ingest: replace spaces and non-URI-safe characters with '-' or '_'.
3. Verify the bucket name passes GCS naming rules (lowercase, digits, dash, dot, 3-222 chars) — validateBucketName runs first, so failures here are usually the object name.
4. Keep the original URISyntaxException (attached cause) when reporting; it names the exact index of the bad character.

Example fix

// before
String objectName = "my file.txt"; // space breaks new URI(...)
URI u = UriPaths.toUri(bucket, objectName, false);

// after
String encoded = Arrays.stream(objectName.split("/", -1))
    .map(s -> URLEncoder.encode(s, StandardCharsets.UTF_8).replace("+", "%20"))
    .collect(Collectors.joining("/"));
URI u = UriPaths.toUri(bucket, encoded, false);

static boolean isUriSafe(String s) {
  return s != null && new org.apache.hadoop.fs.Path(s).toUri().isAbsolute()
      ? true : false;
}
// stricter: try the exact construction UriPaths uses
static boolean uriConstructs(String bucket, String object) {
  try {
    new java.net.URI("gs", bucket, "/" + object, null, null);
    return true;
  } catch (URISyntaxException e) { return false; }
}

static String encodeSegment(String s) {
  try {
    return java.net.URLEncoder.encode(s, "UTF-8").replace("+", "%20");
  } catch (UnsupportedEncodingException e) { throw new AssertionError(e); }
}
// guard: return encoded copy only when raw differs
static String safeSegment(String s) { return s.matches("[A-Za-z0-9._~-]+") ? s : encodeSegment(s); }

try {
  return UriPaths.toUri(bucket, object, allowEmpty);
} catch (IllegalArgumentException e) {
  if (e.getCause() instanceof URISyntaxException) {
    throw new UserInputException("Key contains URI-unsafe characters: "
        + bucket + "/" + object, e);
  }
  throw e;
}

When it happens

Trigger: Calling UriPaths.toUri (directly or via GoogleCloudStorageFileSystem/GHFS APIs that reconstruct URIs from decoded bucket+object pairs) with a bucket name containing spaces or uppercase/underscore-incompatible characters, or an object name containing characters like ' ', '{', '}', '|', '\\', '^', '"', '<', '>', '`' or raw '%' that break URI syntax.

Common situations: Porting keys from S3/HDFS that contain spaces or Unicode; user-supplied filenames pasted into paths; percent-encoding lost after string round-trips; log scrubbing that injects template characters into keys.

Related errors

• GCS path must not have consecutive '/' characters: '%s'
• Object %s already exists.
• Error accessing Bucket %s
• Error accessing %s
• Bucket doesn't match for source '%s' and destination '%s'!

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