{"record":{"id":"5f983d56744f2481","repo":"apache/hadoop","slug":"this-api-cannot-be-supported-without-default-cl","errorCode":null,"errorMessage":"This API:{} cannot be supported without default cluster(that is linkFallBack).","messagePattern":"This API:(.+?) cannot be supported without default cluster\\(that is linkFallBack\\)\\.","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":408,"sourceCode":"    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 {\n    if (this.vfs == null) {\n      return super\n          .primitiveCreate(f, absolutePermission, flag, bufferSize, replication,\n              blockSize, progress, checksumOpt);\n    }\n    ViewFileSystemOverloadScheme.MountPathInfo<FileSystem> mountPathInfo =\n        this.vfs.getMountPathInfo(f, getConf());\n    checkDFS(mountPathInfo.getTargetFs(), \"primitiveCreate\");\n    return ((DistributedFileSystem) mountPathInfo.getTargetFs())","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java#L390-L426","documentation":"checkDefaultDFS throws UnsupportedOperationException when ViewDistributedFileSystem has no default cluster to fall back on (fs == null). Certain APIs are only meaningful against a default cluster; in overload-scheme ViewHDFS that default is supplied by the linkFallback mount entry. Without it, the API cannot run.","triggerScenarios":"Using ViewHDFS (vfs != null) with a mount table that defines no linkFallback to a default HDFS cluster, then calling an API guarded by checkDefaultDFS that requires a default cluster.","commonSituations":"Mount-table XML missing the fallback entry; ops tooling assuming a default cluster exists as in classic fallback ViewFS; partial migration to the viewfs overload scheme.","solutions":["Add a linkFallback entry to the ViewFileSystemOverloadScheme mount table pointing at the default HDFS cluster, then reload the configuration","Or invoke the API directly on the intended cluster's DistributedFileSystem"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Detect missing fallback early: a ViewHDFS in mount mode with no default cluster\nif (viewFs instanceof ViewDistributedFileSystem\n    && !((ViewDistributedFileSystem) viewFs).getChildFileSystems().isEmpty()\n    && noLinkFallbackConfigured(conf)) {\n  throw new IllegalStateException(\n      \"no linkFallback default cluster configured for the view\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  needsDefaultClusterApi(viewFs);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage() != null\n      && e.getMessage().contains(\"without default cluster\")) {\n    // route the call to a concrete cluster's DistributedFileSystem\n  } else {\n    throw e;\n  }\n}","preventionTips":["Configure a linkFallback mount for the overload-scheme view when deploying ViewHDFS","Validate the mount table (links + fallback) during cluster config review, before apps depend on default-cluster APIs"],"tags":["hdfs","viewfs","mount-table","link-fallback","config"],"backgroundTag":"viewfs-unsupported-dfs-api","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}