apache/hadoop · error · UnsupportedOperationException

Not implemented by the

Error message

Not implemented by the ${getClass().getSimpleName()} FileSystem implementation

What it means

FileSystem.getScheme() is an optional override introduced in Hadoop 2.x; the base implementation deliberately throws UnsupportedOperationException so subclasses that never overrode it fail loudly. The guaranteed source of the scheme is getUri().getScheme(), since getUri() is abstract and always implemented.

Solutions

  1. Use fs.getUri().getScheme() instead - it always works
  2. If you own the implementation, override getScheme() to return the registered scheme constant
  3. Restrict direct getScheme() calls to known implementations (DistributedFileSystem, LocalFileSystem, ...)

Example fix

// before
String scheme = fs.getScheme(); // UnsupportedOperationException on non-overriding implementations

// after
String scheme = fs.getUri().getScheme();
Defensive patterns

Strategy: fallback

Validate before calling

public static String schemeOf(FileSystem fs) {
  URI u = fs.getUri();
  return (u == null) ? null : u.getScheme();
}

Try / catch

try {
  scheme = fs.getScheme();
} catch (UnsupportedOperationException e) {
  scheme = fs.getUri().getScheme(); // base-class default is unimplemented
}

Prevention

When it happens

Trigger: Calling getScheme() on a custom or third-party FileSystem subclass that did not override the method, or generic utility code that calls getScheme() on every FileSystem for registration or capability checks.

Common situations: FileSystems written against Hadoop 1.x APIs and recompiled against 2.x+; glue code selecting implementations by comparing schemes.

Related errors

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

Appendix: source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java:362

      scheme = name.getScheme();
    }
    statistics = getStatistics(scheme, getClass());
    resolveSymlinks = conf.getBoolean(
        CommonConfigurationKeysPublic.FS_CLIENT_RESOLVE_REMOTE_SYMLINKS_KEY,
        CommonConfigurationKeysPublic.FS_CLIENT_RESOLVE_REMOTE_SYMLINKS_DEFAULT);
  }

  /**
   * Return the protocol scheme for this FileSystem.
   * <p>
   * This implementation throws an <code>UnsupportedOperationException</code>.
   *
   * @return the protocol scheme for this FileSystem.
   * @throws UnsupportedOperationException if the operation is unsupported
   *         (default).
   */
  public String getScheme() {
    throw new UnsupportedOperationException("Not implemented by the "
        + getClass().getSimpleName() + " FileSystem implementation");
  }

  /**
   * Returns a URI which identifies this FileSystem.
   *
   * @return the URI of this filesystem.
   */
  public abstract URI getUri();

  /**
   * Return a canonicalized form of this FileSystem's URI.
   *
   * The default implementation simply calls {@link #canonicalizeUri(URI)}
   * on the filesystem's own URI, so subclasses typically only need to
   * implement that method.
   *
   * @see #canonicalizeUri(URI)

View on GitHub (pinned to 2add963021)