apache/hadoop · error · IllegalArgumentException

Wrong scheme: %s, in path: %s, expected scheme: %s

Error message

Wrong scheme: %s, in path: %s, expected scheme: %s

What it means

GoogleHadoopFileSystem.checkPath validates the scheme of every Path handed to this FileSystem instance: if the path carries a non-null scheme that does not case-insensitively equal the connector's scheme (gs), it throws IllegalArgumentException. This fires before any GCS call, as part of Hadoop's path-qualification contract.

Source

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

  private GoogleCredentials getCredentials(GoogleHadoopFileSystemConfiguration config)
      throws IOException {
    return getCredentials(config, GCS_CONFIG_PREFIX);
  }

  static GoogleCredentials getCredentials(GoogleHadoopFileSystemConfiguration config,
      String... keyPrefixesVararg) throws IOException {
    return HadoopCredentialsConfiguration.getCredentials(config.getConfig(), keyPrefixesVararg);
  }

  @Override
  protected void checkPath(final Path path) {
    LOG.trace("checkPath(path: {})", path);
    // Validate scheme
    URI uri = path.toUri();

    String scheme = uri.getScheme();
    if (scheme != null && !scheme.equalsIgnoreCase(getScheme())) {
      throw new IllegalArgumentException(
          String.format("Wrong scheme: %s, in path: %s, expected scheme: %s", scheme, path,
              getScheme()));
    }

    String bucket = uri.getAuthority();
    String rootBucket = fsRoot.toUri().getAuthority();

    // Bucket-less URIs will be qualified later
    if (bucket == null || bucket.equals(rootBucket)) {
      return;
    }

    throw new IllegalArgumentException(
        String.format("Wrong bucket: %s, in path: %s, expected bucket: %s", bucket, path,
            rootBucket));
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

1. Use gs:// URIs (or scheme-less relative paths, which get qualified against the FileSystem root).
2. Route each path to its own FileSystem via path.getFileSystem(conf) instead of reusing one instance.
3. Normalize/strip schemes from user-supplied paths before passing them to a specific FileSystem.

Example fix

// before
FileSystem fs = FileSystem.get(new URI("gs://bucket"), conf);
fs.exists(new Path("s3a://bucket/key")); // IllegalArgumentException: Wrong scheme

// after
fs.exists(new Path("gs://bucket/key"));
// or: new Path("s3a://bucket/key").getFileSystem(conf) for the right store

static boolean schemeOk(FileSystem fs, Path p) {
  String s = p.toUri().getScheme();
  return s == null || s.equalsIgnoreCase(fs.getScheme());
}
// use: if (schemeOk(fs, path)) fs.open(path); else path.getFileSystem(conf)...

static boolean isGcsPath(Path p) {
  String s = p.toUri().getScheme();
  return s == null || "gs".equalsIgnoreCase(s);
}

catch IllegalArgumentException with message startsWith("Wrong scheme") - fix the path's scheme or route it to path.getFileSystem(conf); retrying unchanged will always fail.

When it happens

Trigger: fs.open(new Path("s3a://bucket/key")) or any operation on an hdfs://file:// path via a GoogleHadoopFileSystem instance; paths parsed from user input or config that retain their original scheme.

Common situations: Configs mixing cloud providers (fs.defaultFS set to one store while job paths point at another); copy-paste between S3 and GCS setups; Paths constructed from external strings without stripping the scheme.

Related errors

• Wrong bucket: %s, in path: %s, expected bucket: %s
• GCS path supports only '%s' scheme, instead got '%s' from '%
• Path without scheme with non-null authority:{path}
• Rename dir to self is forbidden
• relative paths not allowed:{path}

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