{"record":{"id":"6ba8cff8c3561cc1","repo":"apache/hadoop","slug":"the-src-snapshot-snapshotpath-already-exists-th","errorCode":null,"errorMessage":"The src snapshot={snapshotPath} already exists. The admin should delete the snapshot before submitting the initial distcp.","messagePattern":"The src snapshot=(.+?) already exists\\. The admin should delete the snapshot before submitting the initial distcp\\.","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-federation-balance/src/main/java/org/apache/hadoop/tools/fedbalance/DistCpProcedure.java","lineNumber":465,"sourceCode":"        latestJob = localJob.getCluster().getJob(JobID.forName(jobId));\n      } catch (InterruptedException e) {\n        throw new IOException(e);\n      }\n      return latestJob == null ? null : new LocalJobStatus(latestJob);\n    } else {\n      return null;\n    }\n  }\n\n  private void pathCheckBeforeInitDistcp() throws IOException {\n    if (dstFs.exists(dst)) { // clean up.\n      throw new IOException(\"The dst path=\" + dst + \" already exists. The admin\"\n          + \" should delete it before submitting the initial distcp job.\");\n    }\n    Path snapshotPath = new Path(src,\n        HdfsConstants.DOT_SNAPSHOT_DIR_SEPARATOR + CURRENT_SNAPSHOT_NAME);\n    if (srcFs.exists(snapshotPath)) {\n      throw new IOException(\"The src snapshot=\" + snapshotPath +\n          \" already exists. The admin should delete the snapshot before\"\n          + \" submitting the initial distcp.\");\n    }\n    srcFs.allowSnapshot(src);\n  }\n\n  /**\n   * Submit distcp job and return jobId.\n   */\n  private String submitDistCpJob(String srcParam, String dstParam,\n      boolean useSnapshotDiff) throws IOException {\n    List<String> command = new ArrayList<>();\n    command.addAll(Arrays\n        .asList(new String[] {\"-async\", \"-update\", \"-append\", \"-pruxgpcab\"}));\n    if (useSnapshotDiff) {\n      command.add(\"-diff\");\n      command.add(LAST_SNAPSHOT_NAME);\n      command.add(CURRENT_SNAPSHOT_NAME);","sourceCodeStart":447,"sourceCodeEnd":483,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-federation-balance/src/main/java/org/apache/hadoop/tools/fedbalance/DistCpProcedure.java#L447-L483","documentation":"Second clause of pathCheckBeforeInitDistcp(): the snapshot fedbalance uses as its working 'current' snapshot (src/.snapshot/<CURRENT_SNAPSHOT_NAME>) must not already exist before the initial distcp is submitted. A leftover snapshot from an aborted earlier run blocks resubmission until an admin deletes it; the code would otherwise call allowSnapshot(src) and rely on creating that snapshot itself.","triggerScenarios":"A previous fedbalance run created its CURRENT snapshot on src and died before finishing; on the next submission srcFs.exists(new Path(src, '.snapshot/' + CURRENT_SNAPSHOT_NAME)) is true and the IOException is thrown.","commonSituations":"Restarting a balance job after the client or scheduler crashed mid-procedure; killing a run between snapshot creation and completion.","solutions":["List snapshots ('hdfs dfs -ls <src>/.snapshot') and delete the fedbalance current snapshot with 'hdfs dfsadmin -deleteSnapshot <src> <name>', then resubmit.","For a clean restart also remove dst and any fedbalance LAST snapshot on src, then re-run the job from the beginning.","Do not hand-create snapshots on src while a balance job is expected to run."],"exampleFix":"hdfs dfs -ls hdfs://ns1/data/.snapshot\n# before: fedbalance's current snapshot still there, job submit fails\nhdfs dfsadmin -deleteSnapshot hdfs://ns1/data <CURRENT_SNAPSHOT_NAME>\n# after: resubmit\nhdfs fedbalance -src hdfs://ns1/data -dst hdfs://ns2/data","handlingStrategy":"validation","validationCode":"Path snap = new Path(src, \".snapshot/\" /* + fedbalance CURRENT_SNAPSHOT_NAME */);\nif (srcFs.exists(snap)) {\n  LOG.warn(\"Leftover fedbalance snapshot {} blocks resubmission; delete it first\", snap);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["After any aborted fedbalance run, list and delete its snapshots on src before retrying.","Treat dst + fedbalance snapshots as one unit when cleaning up failed runs."],"tags":["fedbalance","federation-balance","hdfs-snapshot","job-recovery","distcp"],"backgroundTag":"hdfs-snapshot-conflict","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}