{"record":{"id":"63da4894e81984ae","repo":"apache/hadoop","slug":"tracking-file-movement-in-basic-filesystem-is-not","errorCode":null,"errorMessage":"Tracking file movement in basic FileSystem is not supported","messagePattern":"Tracking file movement in basic FileSystem is not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java","lineNumber":1246,"sourceCode":"   *            {@link PathHandle} reference.\n   */\n  protected PathHandle createPathHandle(FileStatus stat,\n      Options.HandleOpt... opts) {\n    if (stat.isDirectory() || stat.isSymlink()) {\n      throw new IllegalArgumentException(\"PathHandle only available for files\");\n    }\n    String authority = stat.getPath().toUri().getAuthority();\n    if (authority != null && !authority.equals(\"file://\")) {\n      throw new IllegalArgumentException(\"Wrong FileSystem: \" + stat.getPath());\n    }\n    Options.HandleOpt.Data data =\n        Options.HandleOpt.getOpt(Options.HandleOpt.Data.class, opts)\n            .orElse(Options.HandleOpt.changed(false));\n    Options.HandleOpt.Location loc =\n        Options.HandleOpt.getOpt(Options.HandleOpt.Location.class, opts)\n            .orElse(Options.HandleOpt.moved(false));\n    if (loc.allowChange()) {\n      throw new UnsupportedOperationException(\"Tracking file movement in \" +\n          \"basic FileSystem is not supported\");\n    }\n    final Path p = stat.getPath();\n    final Optional<Long> mtime = !data.allowChange()\n        ? Optional.of(stat.getModificationTime())\n        : Optional.empty();\n    return new LocalFileSystemPathHandle(p.toString(), mtime);\n  }\n\n  @Override\n  public boolean supportsSymlinks() {\n    return true;\n  }\n\n  @SuppressWarnings(\"deprecation\")\n  @Override\n  public void createSymlink(Path target, Path link, boolean createParent)\n      throws IOException {","sourceCodeStart":1228,"sourceCodeEnd":1264,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java#L1228-L1264","documentation":"Thrown by RawLocalFileSystem.createPathHandle when the caller requests a location-tolerant handle via Options.HandleOpt.moved(true) (or any Location option that allows change). The local FileSystem builds its handle purely from the path string plus mtime, so it cannot track a file that is renamed or moved; only content-stable (moved(false)) handles are supported. Requesting a capability the basic FileSystem lacks is rejected with UnsupportedOperationException.","triggerScenarios":"fs.getPathHandle(stat, Options.HandleOpt.moved(true)) on RawLocalFileSystem/LocalFileSystem; generic client code that always requests the most permissive opts (changed(false), moved(true)) and runs against file:// URIs.","commonSituations":"Porting an HDFS-based application (where HdfsPathHandle tolerates movement) to local FS for testing or edge-node execution; shared library code that hardcodes HandleOpts across filesystems.","solutions":["Use the default location constraint: call getPathHandle(stat) or pass Options.HandleOpt.moved(false)","Branch on filesystem capabilities: request moved(true) only for filesystems whose handles support it (HDFS)","Catch UnsupportedOperationException and fall back to opening the file by path when running on local FS"],"exampleFix":"// before\nPathHandle h = fs.getPathHandle(stat, Options.HandleOpt.moved(true));\n\n// after\nPathHandle h = fs.getPathHandle(stat, Options.HandleOpt.moved(false));","handlingStrategy":"validation","validationCode":"Options.HandleOpt[] opts = (fs instanceof LocalFileSystem || fs instanceof RawLocalFileSystem)\n    ? new Options.HandleOpt[]{ Options.HandleOpt.moved(false) }\n    : new Options.HandleOpt[]{ Options.HandleOpt.moved(true) };\nPathHandle h = fs.getPathHandle(stat, opts);","typeGuard":null,"tryCatchPattern":"try {\n  h = fs.getPathHandle(stat, Options.HandleOpt.moved(true));\n} catch (UnsupportedOperationException e) {\n  // basic FS cannot track movement; degrade to path+mtime handle\n  h = fs.getPathHandle(stat, Options.HandleOpt.moved(false));\n}","preventionTips":["Default to moved(false); request location tolerance only when the target FS documents support","Feature-detect handle capabilities per FileSystem scheme instead of assuming HDFS semantics everywhere"],"tags":["hadoop","local-filesystem","pathhandle","unsupported-operation"],"backgroundTag":"unsupported-filesystem-capability","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}