apache/hadoop · error · IllegalArgumentException

GCS path supports only '%s' scheme, instead got '%s' from '%

Error message

GCS path supports only '%s' scheme, instead got '%s' from '%s'.

What it means

StorageResourceId.fromUriPath requires the URI scheme to be exactly 'gs' (the SCHEME constant, case-sensitive); anything else (hdfs, s3a, file, an odd-case 'GS') throws IllegalArgumentException showing the offending scheme and full URI. This is the connector's lowest-level URI-to-resource parser used by both GoogleCloudStorageFileSystem and the Hadoop layer.

Source

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

    return fromUriPath(path, allowEmptyObjectName, UNKNOWN_GENERATION_ID);
  }

  /**
   * Validates the given URI and if valid, returns the associated StorageResourceId.
   *
   * @param path                 The GCS URI to validate.
   * @param allowEmptyObjectName If true, a missing object name is not considered invalid.
   * @param generationId         The generationId to be used with precondition checks when
   *                             using this
   * @return a StorageResourceId that may be the GCS root, a Bucket, or a StorageObject.
   */
  static StorageResourceId fromUriPath(URI path, boolean allowEmptyObjectName,
      long generationId) {
    LOG.trace("fromUriPath('{}', {})", path, allowEmptyObjectName);
    checkNotNull(path);

    if (!SCHEME.equals(path.getScheme())) {
      throw new IllegalArgumentException(
          String.format("GCS path supports only '%s' scheme, instead got '%s' from '%s'.", SCHEME,
              path.getScheme(), path));
    }

    if (path.equals(GoogleCloudStorageFileSystem.GCSROOT)) {
      return ROOT;
    }

    String bucketName = StringPaths.validateBucketName(path.getAuthority());
    // Note that we're using getPath here instead of rawPath, etc. This is because it is assumed
    // that the path was properly encoded in getPath (or another similar method):
    String objectName = StringPaths.validateObjectName(path.getPath(), allowEmptyObjectName);

    return isNullOrEmpty(objectName) ?
        new StorageResourceId(bucketName, generationId) :
        new StorageResourceId(bucketName, objectName, generationId);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Normalize the URI scheme to lowercase 'gs' before calling fromUriPath.
2. Route non-gs paths to their own FileSystem instead of the GCS connector.
3. Where the scheme is untrusted, build StorageResourceId from bucket/object name strings directly instead of parsing a URI.

Example fix

// before
StorageResourceId id = StorageResourceId.fromUriPath(URI.create("s3a://bucket/obj"), false);
// -> IllegalArgumentException: GCS path supports only 'gs' scheme

// after
URI gcsUri = URI.create("gs://bucket/obj");
StorageResourceId id = StorageResourceId.fromUriPath(gcsUri, false);

URI u = raw.toUri();
if (!"gs".equals(u.getScheme())) {
  u = URI.create("gs://" + u.getAuthority() + u.getPath()); // normalize before parsing
}
StorageResourceId id = StorageResourceId.fromUriPath(u, false);

static boolean isGcsUri(URI u) {
  return u != null && "gs".equals(u.getScheme()); // scheme match is case-sensitive
}

catch IllegalArgumentException with message startsWith("GCS path supports only") - fix or normalize the scheme at the call site; the message shows the offending URI.

When it happens

Trigger: fromUriPath(URI.create("hdfs://bucket/obj")); passing Path.toUri() values obtained from another FileSystem; uppercase scheme variants like 'GS://bucket/obj'; URIs built by string concatenation with the wrong prefix.

Common situations: Connector code receiving paths from external systems; tests constructing generic URIs; scheme normalization bugs where the scheme is dropped or re-cased; mixed-store utility code reusing one URI builder.

Related errors

• Wrong scheme: %s, in path: %s, expected scheme: %s
• Path without scheme with non-null authority:{path}
• Rename dir to self is forbidden
• Wrong bucket: %s, in path: %s, expected bucket: %s
• GCS bucket name cannot be empty.

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