What causes "ProvidedReplica does not support renaming data" in apache/hadoop?

Skip renameData() when the replica is PROVIDED (instanceof ProvidedReplica or ProvidedVolume check); provided data is address-stable.

apache/hadoop · error · UnsupportedOperationException

ProvidedReplica does not support renaming data

Error message

ProvidedReplica does not support renaming data

What it means

ProvidedReplica wraps an immutable FileRegion in a remote filesystem; its data URI is fixed at construction. renameData(URI) unconditionally throws UnsupportedOperationException because the DataNode cannot rename objects inside the external provided store.

Source

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

  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");
  }

  @Override
  public void bumpReplicaGS(long newGS) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not yet support writes");

View on GitHub (pinned to 2add963021)

Solutions

Skip renameData() when the replica is PROVIDED (instanceof ProvidedReplica or ProvidedVolume check); provided data is address-stable.
Exclude PROVIDED volumes from any volume-choosing/moving logic (SupportedOperation checks on the volume).
If writes must land somewhere, target a local volume instead of the provided one.
Catch UnsupportedOperationException defensively at the caller boundary and log the immovable block.

Example fix

// before
boolean ok = replica.renameData(destUri);

// after
boolean ok = !(replica instanceof ProvidedReplica) && replica.renameData(destUri);

Defensive patterns

Strategy: validation

Validate before calling

if (!(replica instanceof ProvidedReplica)) {
  replica.renameData(destUri);
}

Type guard

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

Try / catch

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

Prevention

Remember provided data URIs are immutable addresses into the remote store.
Exclude provided volumes from move/migrate plans.
Check FsVolumeSpi capabilities before attempting data relocation.

When it happens

Trigger: Calling renameData(destURI) on a ProvidedReplica - e.g. recovery/finalize code or block-migration utilities that relocate block data files by URI, applied to a replica on a PROVIDED volume.

Common situations: Running block-movement tooling (disk balancer plans, balancer-driven moves, custom volume migrations) against a DataNode configured with provided storage, or unit tests exercising ReplicaInfo.renameData on ProvidedReplica instances.

Related errors

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