apache/hadoop · error · IOException

Har: rename not allowed

Error message

Har: rename not allowed

What it means

rename is rejected with 'Har: rename not allowed': member names are recorded in the archive index, which is immutable after `hadoop archive` completes, so no path inside a har can be moved. This override throws unconditionally for all src/dst under har://.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java:756

        fs.close();
      } catch(IOException ie) {
        //this might already be closed
        // ignore
      }
    }
  }
  
  /**
   * Not implemented.
   */
  @Override
  public boolean setReplication(Path src, short replication) throws IOException{
    throw new IOException("Har: setReplication not allowed");
  }

  @Override
  public boolean rename(Path src, Path dst) throws IOException {
    throw new IOException("Har: rename not allowed");
  }

  @Override
  public FSDataOutputStream append(Path f) throws IOException {
    throw new IOException("Har: append not allowed");
  }

  /**
   * Not implemented.
   */
  @Override
  public boolean truncate(Path f, long newLength) throws IOException {
    throw new IOException("Har: truncate not allowed");
  }

  /**
   * Not implemented.
   */

View on GitHub (pinned to 2add963021)

Solutions

1. Do renames in a staging directory on the underlying HDFS before creating the archive
2. If the layout must change, rebuild the archive from source with the new structure using `hadoop archive`
3. Make commit/rename logic fall back to copy+delete on the underlying filesystem when the destination is read-only, or reject har destinations up front

Example fix

// before
fs.rename(tmpPath, new Path("har://hdfs-nn:8020/a/data.har/final"));

// after
// rename in HDFS staging, then archive the finalized tree
hdfs.rename(new Path("/a/staging/final"), new Path("/a/data/final"));
// hadoop archive -archiveName data.har -p /a/data /a

if ("har".equals(src.toUri().getScheme()) || "har".equals(dst.toUri().getScheme())) {
  throw new UnsupportedOperationException("rename is not supported on har; rebuild the archive instead");
}

try {
  fs.rename(src, dst);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("not allowed")) {
    // destination is read-only: fall back to copy-on-write semantics on the underlying fs
  }
  throw e;
}

When it happens

Trigger: fs.rename(src, dst) where either path is under har:// — atomic-commit patterns (write temp then rename), directory reorganization jobs, and generic file-movement utilities are the usual callers.

Common situations: Output committers that stage to a temp name and rename into place; migration scripts unaware the destination tree contains har mounts; cleanup/rename tooling run over mixed trees.

Related errors

• Har: create not allowed.
• Har: append not allowed.
• Har: setReplication not allowed
• Har: truncate not allowed
• Har: delete not allowed

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/9d69cb1c77d23e47. Report an issue: GitHub.