{"record":{"id":"5d38b08d1c6eb073","repo":"apache/hadoop","slug":"does-not-match-target-filesystem","errorCode":null,"errorMessage":"Does not match target filesystem","messagePattern":"Does not match target filesystem","errorType":"exception","errorClass":"PathIOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/MoveCommands.java","lineNumber":118,"sourceCode":"      \"Move files that match the specified file pattern <src> \" +\n      \"to a destination <dst>.  When moving multiple files, the \" +\n      \"destination must be a directory.\";\n\n    @Override\n    protected void processOptions(LinkedList<String> args) throws IOException {\n      CommandFormat cf = new CommandFormat(2, Integer.MAX_VALUE);\n      cf.parse(args);\n      getRemoteDestination(args);\n    }\n\n    @Override\n    protected void processPath(PathData src, PathData target) throws IOException {\n      String srcUri = src.fs.getUri().getScheme() + \"://\" +\n          src.fs.getUri().getHost();\n      String dstUri = target.fs.getUri().getScheme() + \"://\" +\n          target.fs.getUri().getHost();\n      if (!srcUri.equals(dstUri)) {\n        throw new PathIOException(src.toString(),\n            \"Does not match target filesystem\");\n      }\n      if (target.exists) {\n        throw new PathExistsException(target.toString());\n      }\n      if (!target.fs.rename(src.path, target.path)) {\n        // we have no way to know the actual error...\n        throw new PathIOException(src.toString());\n      }\n    }\n  }\n}\n","sourceCodeStart":100,"sourceCodeEnd":131,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/MoveCommands.java#L100-L131","documentation":"Rename (the 'mv' command) processPath (MoveCommands.java:118) builds 'scheme://host' strings for the source and destination FileSystems and throws PathIOException('Does not match target filesystem') when they differ. Rename is a metadata-only operation, so it cannot cross filesystem or cluster boundaries; the check prevents attempting it.","triggerScenarios":"'hadoop fs -mv /path file:///local/path', 'hadoop fs -mv hdfs://ns1/path hdfs://ns2/path' (different nameservices/HA namespaces), moving between the default FS and an explicitly-qualified different cluster URI, or between S3A/scheme-mounted mounts and HDFS. The comparison uses scheme+host only, so two mounts of the same cluster via different HA aliases also mismatch.","commonSituations":"Data migration scripts that parameterize source/dest URIs and occasionally span clusters; views/mount-table configurations (HDFS Router Federation) where src and dst resolve to different namespaces; mixing relative paths (default fs) with fully-qualified URIs of another cluster.","solutions":["Use copy-then-delete for cross-filesystem moves: 'hadoop fs -cp -f <src> <dst> && hadoop fs -rm <src>'","Use DistCp (hadoop distcp) for cross-cluster or large-scale moves","Ensure both sides of a same-cluster mv resolve to the same scheme://host — drop explicit URIs and rely on the default filesystem, or use identical HA nameservice identifiers"],"exampleFix":"# before\nhadoop fs -mv /staging/part-0007 s3a://archive/bucket/part-0007\n# mv: `/staging/part-0007': Does not match target filesystem\n\n# after\nhadoop fs -cp -f /staging/part-0007 s3a://archive/bucket/part-0007 \\\n  && hadoop fs -rm /staging/part-0007","handlingStrategy":"validation","validationCode":"// same-filesystem guard before rename\nURI s = srcFs.getUri(), d = dstFs.getUri();\nboolean sameFs = Objects.equals(s.getScheme(), d.getScheme())\n    && Objects.equals(s.getHost(), d.getHost());\nif (!sameFs) { /* copy + delete instead of rename */ }","typeGuard":null,"tryCatchPattern":"catch (PathIOException e) when 'Does not match target filesystem' -> switch to copyThenDelete(src, dst) (fs.copy + fs.delete) or DistCp for bulk","preventionTips":["Remember mv is metadata-only; never cross clusters","Compare scheme+host of both sides before attempting rename","Use DistCp for cross-cluster migration jobs"],"tags":["mv","rename","cross-filesystem","hadoop-shell","uri-mismatch"],"backgroundTag":"cross-filesystem-move","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}