{"record":{"id":"254e3d62e2601bcb","repo":"apache/hadoop","slug":"the-destination-cluster-must-be-specified-254e3d","errorCode":null,"errorMessage":"The destination cluster must be specified.","messagePattern":"The destination cluster must be specified\\.","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-federation-balance/src/main/java/org/apache/hadoop/tools/fedbalance/FedBalance.java","lineNumber":158,"sourceCode":"\n    /**\n     * Specify the threshold of diff entries.\n     * @param value the threshold of a fast distcp.\n     */\n    public Builder setDiffThreshold(int value) {\n      this.diffThreshold = value;\n      return this;\n    }\n\n    /**\n     * Build the balance job.\n     */\n    public BalanceJob build() throws IOException {\n      // Construct job context.\n      FedBalanceContext context;\n      Path dst = new Path(inputDst);\n      if (dst.toUri().getAuthority() == null) {\n        throw new IOException(\"The destination cluster must be specified.\");\n      }\n      Path src = new Path(inputSrc);\n      if (src.toUri().getAuthority() == null) {\n        throw new IOException(\"The source cluster must be specified.\");\n      }\n      context = new FedBalanceContext.Builder(src, dst, NO_MOUNT, getConf())\n          .setForceCloseOpenFiles(forceCloseOpen).setUseMountReadOnly(false)\n          .setMapNum(map).setBandwidthLimit(bandwidth).setTrash(trashOpt)\n          .setDiffThreshold(diffThreshold).build();\n\n      LOG.info(context.toString());\n      // Construct the balance job.\n      BalanceJob.Builder<BalanceProcedure> builder = new BalanceJob.Builder<>();\n      DistCpProcedure dcp =\n          new DistCpProcedure(DISTCP_PROCEDURE, null, delayDuration, context);\n      builder.nextProcedure(dcp);\n      TrashProcedure tp =\n          new TrashProcedure(TRASH_PROCEDURE, null, delayDuration, context);","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-federation-balance/src/main/java/org/apache/hadoop/tools/fedbalance/FedBalance.java#L140-L176","documentation":"FedBalance.BalanceJob.Builder.build() requires a fully-qualified destination URI: the authority component (nameservice or namenode host:port) identifies the destination cluster, which is mandatory because fedbalance copies across clusters. If new Path(inputDst).toUri().getAuthority() is null - a relative path or one without an authority - the IOException is thrown before any job object is built.","triggerScenarios":"Passing -dst /some/path (no scheme/authority), or a URI form whose authority is empty, to the fedbalance CLI. dst.toUri().getAuthority() returns null and build() fails.","commonSituations":"Copy-pasting a plain path that works with 'hdfs dfs -cp'; forgetting the nameservice in router-federation deployments; assuming fs.defaultFS will be applied (fedbalance deliberately does not infer it).","solutions":["Set -dst to a fully-qualified URI: hdfs://<nameservice-or-namenode>:<port>/path.","Confirm the nameservice you name is defined in the client's hdfs-site.xml (dfs.nameservices / dfs.ha.namenodes).","Apply the same fully-qualified form to -src, which is checked next and fails with its own message."],"exampleFix":"# before\nhdfs fedbalance -src hdfs://ns1/data -dst /balance/data\n\n# after\nhdfs fedbalance -src hdfs://ns1/data -dst hdfs://ns2/balance/data","handlingStrategy":"validation","validationCode":"String dstStr = \"hdfs://ns2/balance/data\";\nURI u = new Path(dstStr).toUri();\nif (u.getAuthority() == null) {\n  throw new IllegalArgumentException(\"fedbalance -dst must include the cluster authority, e.g. hdfs://ns2/path\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass fully-qualified URIs (hdfs://<nameservice>/path) to fedbalance for both src and dst.","Never reuse bare 'hdfs dfs' paths in fedbalance commands."],"tags":["fedbalance","federation-balance","uri-validation","path","cluster-addressing"],"backgroundTag":"missing-filesystem-authority","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}