apache/hadoop · error · NotInMountpointException

getXAttrs on path `{}' is not within a mount point

Error message

getXAttrs on path `{}' is not within a mount point

What it means

ViewFileSystem is a mount-table overlay: each path must resolve to a child FileSystem via a configured link before an operation can be forwarded. getXAttr(Path,String) on ViewFileSystem's InternalDirOfViewFs throws NotInMountpointException when the path resolves only to a virtual internal mount-table directory (e.g. "/" or an ancestor like /data when only /data/ds1 is mounted). Note NotInMountpointException extends UnsupportedOperationException, so it is unchecked and slips past handlers that only catch IOException.

Source

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

          .addEntries(AclUtil.getMinimalAcl(PERMISSION_555))
          .stickyBit(false).build();
    }

    @Override
    public void setXAttr(Path path, String name, byte[] value,
        EnumSet<XAttrSetFlag> flag) throws IOException {
      checkPathIsSlash(path);
      throw readOnlyMountTable("setXAttr", path);
    }

    @Override
    public byte[] getXAttr(Path path, String name) throws IOException {
      throw new NotInMountpointException(path, "getXAttr");
    }

    @Override
    public Map<String, byte[]> getXAttrs(Path path) throws IOException {
      throw new NotInMountpointException(path, "getXAttrs");
    }

    @Override
    public Map<String, byte[]> getXAttrs(Path path, List<String> names)
        throws IOException {
      throw new NotInMountpointException(path, "getXAttrs");
    }

    @Override
    public List<String> listXAttrs(Path path) throws IOException {
      throw new NotInMountpointException(path, "listXAttrs");
    }

    @Override
    public void removeXAttr(Path path, String name) throws IOException {
      checkPathIsSlash(path);
      throw readOnlyMountTable("removeXAttr", path);
    }

View on GitHub (pinned to 2add963021)

Solutions

  1. Call getXAttr on a concrete mounted path (below a mount point) rather than the virtual parent/root
  2. Add a mount-table link covering the path: fs.viewfs.mounttable.<cluster>.link.<path>=<target-uri>
  3. Configure root coverage (fs.viewfs.mounttable.<cluster>.linkMergeSlash or linkFallback) so / resolves to a real FileSystem
  4. Catch NotInMountpointException and treat it as 'no xattrs' when walking trees

Example fix

// before
byte[] v = fs.getXAttr(new Path("/"), "user.tag"); // throws NotInMountpointException

// after
try {
  byte[] v = fs.getXAttr(p, "user.tag");
} catch (NotInMountpointException e) {
  v = null; // virtual mount-table dir: no xattrs
}
Defensive patterns

Strategy: try-catch

Validate before calling

static boolean isInMountPoint(ViewFileSystem vfs, Path p) {
  String s = p.toUri().getPath();
  for (MountPoint mp : vfs.getMountPoints()) {
    String m = mp.getMountedOnPath().toUri().getPath();
    if (s.equals(m) || s.startsWith(m.endsWith("/") ? m : m + "/")) return true;
  }
  return false;
}
// if (!isInMountPoint(vfs, p)) skip xattr read

Try / catch

try {
  byte[] v = fs.getXAttr(p, name);
} catch (NotInMountpointException e) { // unchecked: NOT caught by IOException handlers
  // virtual mount-table dir -> treat as absent
}

Prevention

When it happens

Trigger: fs.getXAttr(new Path("/"), "user.myattr") or fs.getXAttr(new Path("/data"), name) on a viewfs:// FileSystem where no link covers /data itself; any xattr read executed while the resolver lands on an internal dir (res.isInternalDir()).

Common situations: distCp -p (preserve xattrs), Hive/Spark jobs, or Ranger/Atlas tag-sync utilities walking a viewfs:// defaultFS root; a mount-table entry missing for the queried prefix after a federation config refresh.

Related errors

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