{"record":{"id":"5f25b3845f7bc4c1","repo":"apache/hadoop","slug":"this-api-is-specific-to-dfs-can-t-run-on-other","errorCode":null,"errorMessage":"This API:{} is specific to DFS. Can't run on other fs:{}","messagePattern":"This API:(.+?) is specific to DFS\\. Can't run on other fs:(.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java","lineNumber":399,"sourceCode":"      final EnumSet<CreateFlag> cflags, final int bufferSize,\n      final short replication, final long blockSize,\n      final Progressable progress, final Options.ChecksumOpt checksumOpt)\n      throws IOException {\n    if (this.vfs == null) {\n      return super\n          .create(f, permission, cflags, bufferSize, replication, blockSize,\n              progress, checksumOpt);\n    }\n    return vfs.create(f, permission, cflags, bufferSize, replication, blockSize,\n        progress, checksumOpt);\n  }\n\n  void checkDFS(FileSystem fs, String methodName) {\n    if (!(fs instanceof DistributedFileSystem)) {\n      String msg = new StringBuilder(\"This API:\").append(methodName)\n          .append(\" is specific to DFS. Can't run on other fs:\")\n          .append(fs.getUri()).toString();\n      throw new UnsupportedOperationException(msg);\n    }\n  }\n\n  void checkDefaultDFS(FileSystem fs, String methodName) {\n    if (fs == null) {\n      String msg = new StringBuilder(\"This API:\").append(methodName).append(\n          \" cannot be supported without default cluster(that is linkFallBack).\")\n          .toString();\n      throw new UnsupportedOperationException(msg);\n    }\n  }\n\n  @Override\n  // DFS specific API\n  protected HdfsDataOutputStream primitiveCreate(Path f,\n      FsPermission absolutePermission, EnumSet<CreateFlag> flag, int bufferSize,\n      short replication, long blockSize, Progressable progress,\n      Options.ChecksumOpt checksumOpt) throws IOException {","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java#L381-L417","documentation":"checkDFS(fs, methodName) throws UnsupportedOperationException when the filesystem resolved for a path is not a DistributedFileSystem. DFS-only APIs exposed on ViewDistributedFileSystem route through this guard, and mounts backed by non-HDFS filesystems (object stores, LocalFS) cannot serve them.","triggerScenarios":"Invoking a DFS-only API (storage policy, quota, snapshot operations guarded by checkDFS) through ViewHDFS where the path resolves to a mount whose target filesystem is not DistributedFileSystem.","commonSituations":"Mount tables mixing HDFS and object-store mounts; legacy admin scripts assuming every mount is HDFS; running DFS-specific commands on viewfs paths that land on non-HDFS targets.","solutions":["Call the API on the concrete target filesystem of that mount instead of through the view","Restrict DFS-only operations to paths mounted on real HDFS clusters","Catch UnsupportedOperationException and degrade gracefully for non-DFS mounts"],"exampleFix":"// before\nviewFs.setStoragePolicy(path, \"COLD\");\n\n// after: resolve the mount target and call the DFS API on it\nViewFileSystemOverloadScheme.MountPathInfo<FileSystem> info =\n    ((ViewDistributedFileSystem) viewFs).getMountPathInfo(path, conf);\nif (info.getTargetFs() instanceof DistributedFileSystem) {\n  ((DistributedFileSystem) info.getTargetFs())\n      .setStoragePolicy(info.getPathOnTarget(), \"COLD\");\n}","handlingStrategy":"validation","validationCode":"ViewFileSystemOverloadScheme.MountPathInfo<FileSystem> info =\n    ((ViewDistributedFileSystem) viewFs).getMountPathInfo(path, conf);\nif (!(info.getTargetFs() instanceof DistributedFileSystem)) {\n  throw new IllegalArgumentException(\n      \"path \" + path + \" is not on an HDFS mount\");\n}\n// safe to call DFS-only API on info.getTargetFs()","typeGuard":"static boolean isOnDfsMount(FileSystem viewFs, Path p, Configuration conf) {\n  if (!(viewFs instanceof ViewDistributedFileSystem)) {\n    return viewFs instanceof DistributedFileSystem;\n  }\n  return ((ViewDistributedFileSystem) viewFs)\n      .getMountPathInfo(p, conf).getTargetFs()\n      instanceof DistributedFileSystem;\n}","tryCatchPattern":"try {\n  dfsOnlyApi(viewFs, path);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"specific to DFS\")) {\n    // path resolved to a non-HDFS mount; route or skip\n  } else {\n    throw e;\n  }\n}","preventionTips":["Resolve mount targets before calling DFS-only APIs on a view","Keep admin scripts on hdfs:// URIs when they need DFS-specific operations"],"tags":["hdfs","viewfs","unsupported-operation","mount-table"],"backgroundTag":"viewfs-unsupported-dfs-api","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}