apache/hadoop · error · UnsupportedOperationException

ProvidedReplica does not support renaming metadata

Error message

ProvidedReplica does not support renaming metadata

What it means

ProvidedReplica represents a replica whose bytes and checksums live in an external provided store; there is no local meta file to move. renameMeta(URI) unconditionally throws UnsupportedOperationException because renaming metadata inside the remote/read-only backing store is outside the DataNode contract.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ProvidedReplica.java:272

  @Override
  public boolean metadataExists() {
    return NULL_CHECKSUM_ARRAY == null ? false : true;
  }

  @Override
  public boolean deleteMetadata() {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not support deleting metadata");
  }

  @Override
  public long getMetadataLength() {
    return NULL_CHECKSUM_ARRAY == null ? 0 : NULL_CHECKSUM_ARRAY.length;
  }

  @Override
  public boolean renameMeta(URI destURI) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not support renaming metadata");
  }

  @Override
  public boolean renameData(URI destURI) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not support renaming data");
  }

  @Override
  public boolean getPinning(LocalFileSystem localFS) throws IOException {
    return false;
  }

  @Override
  public void setPinning(LocalFileSystem localFS) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not support pinning");

View on GitHub (pinned to 2add963021)

Solutions

1. Check instanceof ProvidedReplica (or ReplicaState/ProvidedVolume) before renameMeta and skip the move for provided replicas.
2. Route block moves to local volumes only; provided replicas are pinned to their remote URI by design.
3. Override renameMeta in a writable ProvidedReplica subclass only if your backend truly supports it.
4. Catch UnsupportedOperationException at the migration boundary and treat that replica as immovable.

Example fix

// before
boolean moved = replica.renameMeta(destUri);

// after
boolean moved = (replica instanceof ProvidedReplica)
    ? false
    : replica.renameMeta(destUri);

if (!(replica instanceof ProvidedReplica)) {
  replica.renameMeta(destUri);
} // provided replicas: nothing to rename, skip silently or log

static boolean isProvided(ReplicaInfo r) {
  return r instanceof ProvidedReplica;
}

try {
  replica.renameMeta(destUri);
} catch (UnsupportedOperationException e) {
  LOG.warn("Cannot rename metadata of PROVIDED replica {}: {}",
      replica.getBlockId(), e.getMessage());
}

When it happens

Trigger: Invoking renameMeta(destURI) on a ProvidedReplica - typically via generic block-relocation code (finalize/recovery paths or test utilities that shuffle replicas between URIs) that was written against LocalReplica and calls renameMeta while migrating a block.

Common situations: Provided storage enabled (PROVIDED volume in dfs.datanode.data.dir) while an upgrade, recovery drill, or custom FsDataset extension attempts standard file-shuffle semantics on provided replicas; also hit in unit tests that build ProvidedReplica objects and exercise the full ReplicaInfo API surface.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ProvidedReplica does not support renaming data
• ProvidedReplica does not support deleting metadata
• ProvidedReplica does not support pinning
• ProvidedReplica does not yet support truncate
• ProvidedReplica does not yet support copy data

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