apache/hadoop · error · UnsupportedFileSystemException

mergefs not implemented yet

Error message

mergefs not implemented yet

What it means

When a mount table declares a merged link (fs.viewfs.mounttable.<n>.linkMerge.<path>=uri1,uri2,...), InodeTree asks the FS for a merged target FileSystem. ViewFs (the FileContext/AbstractFileSystem implementation) answers with UnsupportedFileSystemException("mergefs not implemented yet") from getTargetFileSystem(String, URI[]) — the MergeFs branch is commented out, so merge links are simply unimplemented in ViewFs.

Source

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

                  +" for uri " + uri + "with exception: " + ex.toString());
            }
            return null;
          }
        };
      }

      @Override
      protected AbstractFileSystem getTargetFileSystem(
          final INodeDir<AbstractFileSystem> dir) throws URISyntaxException {
        return new InternalDirOfViewFs(dir, creationTime, ugi, getUri(), this,
            config);
      }

      @Override
      protected AbstractFileSystem getTargetFileSystem(final String settings,
          final URI[] mergeFsURIList)
          throws URISyntaxException, UnsupportedFileSystemException {
        throw new UnsupportedFileSystemException("mergefs not implemented yet");
        // return MergeFs.createMergeFs(mergeFsURIList, config);
      }
    };
    renameStrategy = ViewFileSystem.RenameStrategy.valueOf(
        conf.get(Constants.CONFIG_VIEWFS_RENAME_STRATEGY,
            ViewFileSystem.RenameStrategy.SAME_MOUNTPOINT.toString()));
  }

  @Override
  @Deprecated
  public FsServerDefaults getServerDefaults() throws IOException {
    return LocalConfigKeys.getServerDefaults();
  }

  @Override
  public FsServerDefaults getServerDefaults(final Path f) throws IOException {
    InodeTree.ResolveResult<AbstractFileSystem> res;
    try {

View on GitHub (pinned to 2add963021)

Solutions

1. Remove the linkMerge entry and mount each child path individually (link.<path>)
2. Use linkNfly (read-only N-fly replication) or linkMergeSlash if one of those semantics fits
3. For a true union namespace, use Router-Based Federation (HDFS RBF) instead of viewfs linkMerge

Example fix

<!-- before (core-site.xml) -->
<property><name>fs.viewfs.mounttable.c1.linkMerge./data</name>
  <value>hdfs://nn1:8020/data,hdfs://nn2:8020/data</value></property>

<!-- after: individual mounts -->
<property><name>fs.viewfs.mounttable.c1.link./data/nn1</name>
  <value>hdfs://nn1:8020/data</value></property>
<property><name>fs.viewfs.mounttable.c1.link./data/nn2</name>
  <value>hdfs://nn2:8020/data</value></property>

static void assertNoMergeLinks(Configuration conf) {
  for (Map.Entry<String, String> e : conf) {
    if (e.getKey().contains(".linkMerge.")) {
      throw new IllegalStateException("ViewFs does not implement linkMerge: " + e.getKey());
    }
  }
}

try {
  fc = FileContext.getFileContext(new URI("viewfs://c1"), conf);
} catch (UnsupportedFileSystemException e) {
  if (e.getMessage().contains("mergefs")) log.error("remove linkMerge entries from the mount table");
}

When it happens

Trigger: Configuring fs.viewfs.mounttable.<n>.linkMerge./data=hdfs://nn1:8020/data,hdfs://nn2:8020/data and then creating a FileContext on viewfs://<n> (initialization builds the InodeTree and hits the throw immediately); configs copied from systems expecting union mounts.

Common situations: Operators migrating off union/federated layouts assuming linkMerge works everywhere (only linkMergeSlash and specific composite FSs like Nfly via linkNfly are implemented); stale documentation or cluster templates carrying linkMerge entries.

Related errors

• getXAttrs on path `{}' is not within a mount point
• listXAttrs on path `{}' is not within a mount point
• getQuotaUsage on path `{}' is not within a mount point
• getStoragePolicy on path `{}' is not within a mount point
• No link found for the given path. on path `{}' is not within

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