{"record":{"id":"c29b386928d8388c","repo":"apache/hadoop","slug":"the-destination-cluster-must-be-specified","errorCode":null,"errorMessage":"The destination cluster must be specified.","messagePattern":"The destination cluster must be specified\\.","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/rbfbalance/RouterFedBalance.java","lineNumber":167,"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 = getSrcPath(inputSrc);\n      String mount = inputSrc;\n      context = new FedBalanceContext.Builder(src, dst, mount, getConf())\n          .setForceCloseOpenFiles(forceCloseOpen).setUseMountReadOnly(true)\n          .setMapNum(map).setBandwidthLimit(bandwidth).setTrash(trashOpt)\n          .setDelayDuration(delayDuration).setDiffThreshold(diffThreshold)\n          .build();\n\n      LOG.info(context.toString());\n      // Construct the balance job.\n      BalanceJob.Builder<BalanceProcedure> builder = new BalanceJob.Builder<>();\n      RouterDistCpProcedure dcp =\n          new RouterDistCpProcedure(DISTCP_PROCEDURE, null, delayDuration,\n              context);\n      builder.nextProcedure(dcp);\n      MountTableProcedure mtp =\n          new MountTableProcedure(MOUNT_TABLE_PROCEDURE, null, delayDuration,","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/rbfbalance/RouterFedBalance.java#L149-L185","documentation":"RouterFedBalance's BalanceJobBuilder.build() validates the fedbalance destination before constructing the job: new Path(inputDst).toUri().getAuthority() must be non-null, i.e. the destination must be a fully-qualified URI carrying a nameservice authority (hdfs://ns1/dest). A destination without an authority leaves FedBalance unable to tell which cluster receives the data, so build() throws this IOException at job construction time.","triggerScenarios":"Invoking `hdfs fedbalance -s /mount -d <dst>` (or the router balance client) with a destination like /dest, dest, or hdfs:///dest — any URI whose authority component is null.","commonSituations":"Users omit the nameservice on -d because the source is a router path and they assume the same namespace applies; scripts ported from DistCp invocations using unqualified paths.","solutions":["Specify the destination with an explicit nameservice authority: hdfs fedbalance -s /mount -d hdfs://ns1/target/path","Confirm the nameservice id matches one in the federation (hdfs dfsrouteradmin -list shows destination namespaces)","Re-run the command and confirm the job submits and the balance proceeds"],"exampleFix":"# before: destination has no authority → IOException(\"The destination cluster must be specified.\")\nhdfs fedbalance -s /apps/data -d /archive/data\n\n# after: fully-qualified destination with nameservice authority\nhdfs fedbalance -s /apps/data -d hdfs://ns1/archive/data","handlingStrategy":"validation","validationCode":"// Validate the fedbalance destination before building/submitting the job\nPath dst = new Path(inputDst);\nif (dst.toUri().getAuthority() == null) {\n  throw new IllegalArgumentException(\n      \"Destination must include a nameservice, e.g. hdfs://ns1/path: \" + inputDst);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass fully-qualified hdfs://nsId/... URIs as fedbalance destinations","Add a CLI pre-flight check that parses the URI authority in wrapper scripts","Cross-check the nameservice id against dfsrouteradmin -list output"],"tags":["hadoop","rbf","fedbalance","cli","uri-validation","client-side"],"backgroundTag":"missing-required-uri-authority","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}