{"record":{"id":"8b10d5ab2bce718d","repo":"apache/hadoop","slug":"har-startlocaloutput-not-allowed","errorCode":null,"errorMessage":"Har: startLocalOutput not allowed","messagePattern":"Har: startLocalOutput not allowed","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java","lineNumber":857,"sourceCode":"    throw new IOException(\"Har: copyfromlocalfile not allowed\");\n  }\n\n  /**\n   * copies the file in the har filesystem to a local file.\n   */\n  @Override\n  public void copyToLocalFile(boolean delSrc, Path src, Path dst) \n    throws IOException {\n    FileUtil.copy(this, src, getLocal(getConf()), dst, false, getConf());\n  }\n  \n  /**\n   * not implemented.\n   */\n  @Override\n  public Path startLocalOutput(Path fsOutputFile, Path tmpLocalFile) \n    throws IOException {\n    throw new IOException(\"Har: startLocalOutput not allowed\");\n  }\n  \n  /**\n   * not implemented.\n   */\n  @Override\n  public void completeLocalOutput(Path fsOutputFile, Path tmpLocalFile) \n    throws IOException {\n    throw new IOException(\"Har: completeLocalOutput not allowed\");\n  }\n  \n  /**\n   * not implemented.\n   */\n  @Override\n  public void setOwner(Path p, String username, String groupname)\n    throws IOException {\n    throw new IOException(\"Har: setowner not allowed\");","sourceCodeStart":839,"sourceCodeEnd":875,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java#L839-L875","documentation":"startLocalOutput(Path fsOutputFile, Path tmpLocalFile) is the first half of FileSystem's local-staging commit protocol used by FileUtil.copy when copying INTO a filesystem: it returns a local temp path, the data is staged there, then completeLocalOutput commits it. HarFileSystem implements the protocol's members as unconditional throws, so any staged copy into a har fails here.","triggerScenarios":"FileUtil.copy(localFs, src, harFs, dst, ...) or any code calling dstFs.startLocalOutput(harPath, tmp) — i.e., a copy-into-har that takes the local temp-file route rather than calling create directly.","commonSituations":"Reusing FileUtil.copy-based helpers with a har destination; porting local-to-remote copy code that relies on the staging protocol for large files.","solutions":["Copy to the underlying HDFS with FileUtil.copy(local, src, hdfs, dst) and rebuild the archive afterwards","Route all 'into archive' flows through `hadoop archive`, which is the only supported writer","Add a destination-scheme guard before invoking FileUtil.copy"],"exampleFix":"// before\nFileUtil.copy(localFs, src, harFs, new Path(\"har://hdfs-nn:8020/a/data.har/f\"), false, conf); // hits startLocalOutput\n\n// after\nFileUtil.copy(localFs, src, hdfs, new Path(\"/a/data/f\"), false, conf);\n// then: hadoop archive -archiveName data.har -p /a/data /a","handlingStrategy":"validation","validationCode":"if (\"har\".equals(dst.toUri().getScheme())) {\n  // FileUtil.copy's local-staging protocol cannot commit into a har\n  throw new UnsupportedOperationException(\"staged copy into har is not supported: \" + dst);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check the destination scheme before invoking FileUtil.copy for local-to-remote transfers","Reserve the startLocalOutput/completeLocalOutput protocol for writable filesystems"],"tags":["hadoop","har-filesystem","read-only","local-output","fileutil-copy"],"backgroundTag":"read-only-filesystem-write","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}