apache/hadoop · error · NotInMountpointException

getLinkTarget on path `<path>' is not within a mount point

Error message

getLinkTarget on path `<path>' is not within a mount point

What it means

ViewFileSystem.getLinkTarget(Path) resolves the path first; a FileNotFoundException from resolve() (no mount point covers the path) is translated into NotInMountpointException('getLinkTarget on path ... is not within a mount point'). Viewfs can only follow symlinks that live inside a mounted file system, so it must reject paths that map to no target.

Source

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

   */
  @Override
  public long getUsed() throws IOException {
    InodeTree.ResolveResult<FileSystem> res = fsState.resolve(
        getUriPath(InodeTree.SlashPath), true);
    if (res.isInternalDir()) {
      throw new NotInMountpointException(InodeTree.SlashPath, "getUsed");
    } else {
      return res.targetFileSystem.getUsed();
    }
  }

  @Override
  public Path getLinkTarget(Path path) throws IOException {
    InodeTree.ResolveResult<FileSystem> res;
    try {
      res = fsState.resolve(getUriPath(path), true);
    } catch (FileNotFoundException e) {
      throw new NotInMountpointException(path, "getLinkTarget");
    }
    return res.targetFileSystem.getLinkTarget(res.remainingPath);
  }

  /**
   * Reject the concat operation; forward the rest to the viewed FS.
   * @param path path to query the capability of.
   * @param capability string to query the stream support for.
   * @return the capability
   * @throws IOException if there is no resolved FS, or it raises an IOE.
   */
  @Override
  public boolean hasPathCapability(Path path, String capability)
      throws IOException {
    final Path p = makeQualified(path);
    switch (validatePathCapabilityArgs(p, capability)) {
    case CommonPathCapabilities.FS_CONCAT:
      // concat is not supported, as it may be invoked across filesystems.

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure the path containing the symlink is mounted (add the fs.viewfs.mounttable.default.link.* entry)
2. Resolve the symlink inside the target file system by operating on the mounted child path directly
3. Configure linkMergeSlash so every path resolves to a backing cluster
4. Catch NotInMountpointException (subclass of UnsupportedOperationException) in symlink-handling utilities and report the unmounted path

Example fix

// before
Path t = fc.getLinkTarget(new Path("viewfs://cluster/lnk")); // throws if path unmounted

// after
Path p = new Path("viewfs://cluster/lnk");
Path t;
try {
  t = fc.getLinkTarget(p);
} catch (UnresolvedLinkException | UnsupportedOperationException e) {
  t = null; // path not covered by viewfs; handle absence of symlink
}

// Only call getLinkTarget on paths that resolve under a mount
if (!fs.exists(p)) {
  throw new FileNotFoundException(p + " not covered by viewfs mount table");
}
Path t = fc.getLinkTarget(p);

try {
  Path target = fc.getLinkTarget(p);
} catch (UnresolvedLinkException | UnsupportedOperationException e) {
  // path is not inside any mount; no symlink semantics available
  target = null;
}

When it happens

Trigger: readlink/getLinkTarget calls on a viewfs path that is outside every mount link, for example via FileContext.getLinkTarget() or symlink-aware input formats resolving a link placed at the viewfs root or in an unmounted directory.

Common situations: Symlinks created at viewfs root before the mount table covered that path; jobs using FileContext with viewfs URIs that resolve link targets on staging paths not in the mount table; partial mount tables during staged migrations.

Related errors

• ViewFs: Non absolute mount name in config:{src}
• Path {nextInode.fullPath} already exists as link
• Path {strB} already exists as dir; cannot create link here
• Unexpected mount table link entry '{key}'. Use linkMergeSlas
• ViewFs: Cannot initialize: Invalid entry in Mount table in c

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