apache/hadoop · error · NotInMountpointException

No link found for the given path. on path `{}' is not within

Error message

No link found for the given path. on path `{}' is not within a mount point

What it means

ViewFileSystemOverloadScheme.getRawFileSystem(Path, Configuration) resolves the path through the mount-table InodeTree to recover the raw backing FileSystem. When fsState.resolve() throws FileNotFoundException (no link at or above the path and no root fallback link configured), it is translated to NotInMountpointException with operation text "No link found for the given path." — the path maps to no mount entry.

Source

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

   * will throw NotInMountpointException. Please note, this API will not return
   * chrooted file system. Instead, this API will get actual raw file system
   * instances.
   *
   * @param path - fs uri path
   * @param conf - configuration
   * @throws IOException raised on errors performing I/O.
   * @return file system.
   */
  public FileSystem getRawFileSystem(Path path, Configuration conf)
      throws IOException {
    InodeTree.ResolveResult<FileSystem> res;
    try {
      res = fsState.resolve(getUriPath(path), true);
      return res.isInternalDir() ? fsGetter().get(path.toUri(), conf)
          : ((ChRootedFileSystem) res.targetFileSystem).getMyFs();
    } catch (FileNotFoundException e) {
      // No link configured with passed path.
      throw new NotInMountpointException(path,
          "No link found for the given path.");
    }
  }

  /**
   * Gets the mount path info, which contains the target file system and
   * remaining path to pass to the target file system.
   *
   * @param path the path.
   * @param conf configuration.
   * @return mount path info.
   * @throws IOException raised on errors performing I/O.
   */
  public MountPathInfo<FileSystem> getMountPathInfo(Path path,
      Configuration conf) throws IOException {
    InodeTree.ResolveResult<FileSystem> res;
    try {
      res = fsState.resolve(getUriPath(path), true);

View on GitHub (pinned to 2add963021)

Solutions

1. Add a mount entry covering the path: fs.viewfs.mounttable.<n>.link.<mountPoint>=<targetFSUri>
2. Configure fs.viewfs.mounttable.<n>.linkFallback=<targetFSUri> so unmatched paths fall through to a default cluster
3. Catch NotInMountpointException and route the path explicitly via its known cluster URI

Example fix

// before
FileSystem raw = vfos.getRawFileSystem(new Path("/logs/app"), conf); // throws

<!-- after: mount table entry in core-site.xml -->
<property><name>fs.viewfs.mounttable.mycluster.link./logs</name>
  <value>hdfs://nnLogs:8020/logs</value></property>

static boolean hasLinkFor(ViewFileSystemOverloadScheme vfos, Path p) {
  String s = p.toUri().getPath();
  return vfos.getMountPoints().stream()
      .map(mp -> mp.getMountedOnPath().toUri().getPath())
      .anyMatch(m -> s.equals(m) || s.startsWith(m.endsWith("/") ? m : m + "/"));
}

try {
  FileSystem raw = vfos.getRawFileSystem(p, conf);
} catch (NotInMountpointException e) {
  // no link covers p and no linkFallback: route via known cluster URI instead
}

When it happens

Trigger: vfsOverload.getRawFileSystem(new Path("/logs/app/1.log"), conf) when no fs.viewfs.mounttable.<n>.link./logs... entry exists and no linkFallback is set; probing paths that appear in data but not in the mount table.

Common situations: Catalog/journal patterns (HBase-like WAL placement, Hive warehouse layout) that recover the physical cluster for a logical path via overload scheme; mount tables loaded from an external config loader (error 985 family) that returned fewer entries than expected.

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
• getStatus on path `{}' is not within a mount point

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