apache/hadoop · error · AccessControlException

Cannot Rename within internal dirs of mount table: src={} is

Error message

Cannot Rename within internal dirs of mount table: src={} is readOnly

What it means

ViewFs.renameInternal resolves the source with resolveLastComponent=false to detect renames of mount points. When src resolves to an internal dir and no root fallback link (fs.viewfs.mounttable.<n>.linkFallback) is configured, there is no real FileSystem to rename from, so it throws AccessControlException("Cannot Rename within internal dirs of mount table: src=<src> is readOnly").

Source

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

      UnresolvedLinkException, IOException {
    InodeTree.ResolveResult<AbstractFileSystem> res =
        fsState.resolve(getUriPath(f), true);
    return res.targetFileSystem.truncate(res.remainingPath, newLength);
  }

  @Override
  public void renameInternal(final Path src, final Path dst,
      final boolean overwrite) throws IOException, UnresolvedLinkException {
    // passing resolveLastComponet as false to catch renaming a mount point
    // itself we need to catch this as an internal operation and fail if no
    // fallback.
    InodeTree.ResolveResult<AbstractFileSystem> resSrc =
        fsState.resolve(getUriPath(src), false);

    if (resSrc.isInternalDir()) {
      if (fsState.getRootFallbackLink() == null) {
        // If fallback is null, we can't rename from src.
        throw new AccessControlException(
            "Cannot Rename within internal dirs of mount table: src=" + src
                + " is readOnly");
      }
      InodeTree.ResolveResult<AbstractFileSystem> resSrcWithLastComp =
          fsState.resolve(getUriPath(src), true);
      if (resSrcWithLastComp.isInternalDir() || resSrcWithLastComp
          .isLastInternalDirLink()) {
        throw new AccessControlException(
            "Cannot Rename within internal dirs of mount table: src=" + src
                + " is readOnly");
      } else {
        // This is fallback and let's set the src fs with this fallback
        resSrc = resSrcWithLastComp;
      }
    }

    InodeTree.ResolveResult<AbstractFileSystem> resDst =
        fsState.resolve(getUriPath(dst), false);

View on GitHub (pinned to 2add963021)

Solutions

1. Configure fs.viewfs.mounttable.<n>.linkFallback=<hdfs-uri> so renames from internal dirs fall through to a real cluster
2. Rename a concrete path inside a mount point instead of the virtual container
3. Catch AccessControlException and surface 'source is a read-only mount table node'

Example fix

<!-- before: no fallback, rename from virtual dir throws -->

<!-- after (core-site.xml): enable fallback cluster -->
<property><name>fs.viewfs.mounttable.c1.linkFallback</name>
  <value>hdfs://nnFallback:8020/fallback</value></property>

// Validate src before rename: must resolve into a mount point or fallback must exist
static boolean renameSrcOk(ViewFileSystem vfs, Path src) {
  String s = src.toUri().getPath();
  boolean mounted = vfs.getMountPoints().stream()
      .anyMatch(mp -> s.startsWith(mp.getMountedOnPath() + "/") && !s.equals(mp.getMountedOnPath().toString()));
  return mounted; // if false, a linkFallback must be configured for the rename to work
}

try {
  fc.rename(src, dst, Rename.NONE);
} catch (AccessControlException ace) {
  if (ace.getMessage().contains("src=") && ace.getMessage().contains("readOnly")) {
    // src is an internal dir and no linkFallback is set
  }
}

When it happens

Trigger: FileContext.rename(viewfs:///user/x, ...) where /user/x is a virtual container dir (mount links only below it) and no linkFallback is set; federation clients where admins deliberately omitted a fallback to keep the root immutable.

Common situations: Data-management jobs moving directories up/down a federated tree; tools coded against plain HDFS that rename from paths which exist only virtually in viewfs.

Related errors

• Cannot Rename within internal dirs of mount table: dest={} i
• Cannot delete internal mount table directory: {}
• 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

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