apache/hadoop · error · UnsupportedFileSystemException

%s=null: %s: %s

Error message

%s=null: %s: %s

What it means

ViewFileSystemOverloadScheme.createFileSystem instantiates the real FileSystem for the overloaded scheme using the key pattern fs.viewfs.overload.scheme.target.<scheme>.impl (FsConstants.FS_VIEWFS_OVERLOAD_SCHEME_TARGET_FS_IMPL_PATTERN). When that key is absent, conf.getClass returns null and initialize fails fast with UnsupportedFileSystemException("fs.<...>.impl=null: No overload scheme fs configured: <scheme>") — no default exists for overloaded schemes.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ViewFileSystemOverloadScheme.java:284

                  + "given target uri scheme. So, the target file system "
                  + "instances will not be cached. To cache fs instances, "
                  + "please set fs.viewfs.enable.inner.cache to true. "
                  + "The target uri is: " + uri);
        }
        return createFileSystem(uri, conf);
      } else {
        return FileSystem.get(uri, conf);
      }
    }

    private FileSystem createFileSystem(URI uri, Configuration conf)
        throws IOException {
      final String fsImplConf = String.format(
          FsConstants.FS_VIEWFS_OVERLOAD_SCHEME_TARGET_FS_IMPL_PATTERN,
          uri.getScheme());
      Class<?> clazz = conf.getClass(fsImplConf, null);
      if (clazz == null) {
        throw new UnsupportedFileSystemException(
            String.format("%s=null: %s: %s", fsImplConf,
                "No overload scheme fs configured", uri.getScheme()));
      }
      FileSystem fs = (FileSystem) newInstance(clazz, uri, conf);
      fs.initialize(uri, conf);
      return fs;
    }

    private <T> T newInstance(Class<T> theClass, URI uri, Configuration conf) {
      T result;
      try {
        Constructor<T> meth = theClass.getConstructor();
        meth.setAccessible(true);
        result = meth.newInstance();
      } catch (InvocationTargetException e) {
        Throwable cause = e.getCause();
        if (cause instanceof RuntimeException) {
          throw (RuntimeException) cause;

View on GitHub (pinned to 2add963021)

Solutions

1. Set fs.viewfs.overload.scheme.target.<scheme>.impl to the concrete FileSystem implementation (e.g. org.apache.hadoop.hdfs.DistributedFileSystem)
2. Confirm the value is a class name, not a URI, and is present on every client/gateway core-site.xml
3. Verify the scheme in the URI matches the scheme used in the property name exactly (case-sensitive)

Example fix

// before (core-site.xml)
<property><name>fs.myscheme.impl</name>
  <value>org.apache.hadoop.fs.viewfs.ViewFileSystemOverloadScheme</value></property>

<!-- after: add the required target impl -->
<property><name>fs.myscheme.impl</name>
  <value>org.apache.hadoop.fs.viewfs.ViewFileSystemOverloadScheme</value></property>
<property><name>fs.viewfs.overload.scheme.target.myscheme.impl</name>
  <value>org.apache.hadoop.hdfs.DistributedFileSystem</value></property>

static void requireOverloadTarget(Configuration conf, String scheme) {
  String key = String.format("fs.viewfs.overload.scheme.target.%s.impl", scheme);
  if (conf.get(key) == null) {
    throw new IllegalArgumentException("Missing required config: " + key);
  }
}

try {
  fs = FileSystem.get(uri, conf);
} catch (UnsupportedFileSystemException e) {
  // message names the missing fs.viewfs.overload.scheme.target.<scheme>.impl key
}

When it happens

Trigger: Configuring fs.myscheme.impl=org.apache.hadoop.fs.viewfs.ViewFileSystemOverloadScheme but omitting fs.viewfs.overload.scheme.target.myscheme.impl, then calling FileSystem.get(new URI("myscheme:///"), conf); also using scheme-agnostic code that obtains the FS via fsGetter() for a root-fallback path before the target impl is configured.

Common situations: Adopting the overload-scheme feature (HADOOP-16796 line of work) to overlay viewfs mounts on an existing scheme (hdfs, s3a, custom); templates that copy fs.<scheme>.impl but forget the matching target key; multi-cluster clients with per-cluster core-site.xml fragments.

Related errors

• Errors on getting mount table loader class. The fs.viewfs.mo
• No link found for the given path. on path `{}' is not within
• Home dir should start with /:{homedir}
• ViewFs: Non absolute mount name in config:{src}
• Path {nextInode.fullPath} already exists as link

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