apache/hadoop · error · UnsupportedOperationException

ProvidedReplica does not yet support copy metadata

Error message

ProvidedReplica does not yet support copy metadata

What it means

copyMetadata(URI destination) copies a replica's checksum meta file alongside its data when a block is copied into this DataNode (FsDatasetImpl.copyBlock). ProvidedReplica throws UnsupportedOperationException because its 'metadata' is the synthesized NULL_CHECKSUM_ARRAY - there is no meta file to copy to a destination URI.

Source

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

      return (int) (info.getBlockLength() - getNumBytes());
    }
  }

  @Override
  public void truncateBlock(long newLength) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not yet support truncate");
  }

  @Override
  public void updateWithReplica(StorageLocation replicaLocation) {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not yet support update");
  }

  @Override
  public void copyMetadata(URI destination) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not yet support copy metadata");
  }

  @Override
  public void copyBlockdata(URI destination) throws IOException {
    throw new UnsupportedOperationException(
        "ProvidedReplica does not yet support copy data");
  }

  @VisibleForTesting
  public void setPathHandle(PathHandle pathHandle) {
    this.pathHandle = pathHandle;
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure PROVIDED volumes are never chosen as replication-landing targets (they only serve pre-existing aliased data).
2. Check instanceof ProvidedReplica / volume type before copyMetadata and abort the copy with a clear error.
3. Fix the volume-choosing policy (available space / supported writes) so writes go to local volumes.
4. Catch UnsupportedOperationException in the copy path and free any partially-created replica before rethrowing.

Example fix

// before
replica.copyMetadata(destUri);

// after
if (replica instanceof ProvidedReplica) {
  throw new IOException("Cannot copy metadata into read-only PROVIDED replica");
}
replica.copyMetadata(destUri);

if (replica instanceof ProvidedReplica) {
  throw new IOException("Cannot copy metadata into read-only PROVIDED replica");
}
replica.copyMetadata(destUri);

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

try {
  replica.copyMetadata(destUri);
} catch (UnsupportedOperationException e) {
  // roll back the partially created replica, then fail the copy
  dataset.invalidate(bpid, replica.getBlock());
  throw new IOException("PROVIDED volume cannot receive metadata copies", e);
}

When it happens

Trigger: Block replication delivers a block to a DataNode and the volume chooser picks a PROVIDED volume; FsDatasetImpl.copyBlock calls copyMetadata(destination) on the newly created FinalizedProvidedReplica to duplicate the source's meta stream.

Common situations: Provided storage configured alongside local volumes, and the NameNode schedules a replication pipeline whose target datanode lands the copy on the provided volume; also custom tests calling copyMetadata directly on ProvidedReplica.

Related errors

• ProvidedReplica does not support deleting metadata
• ProvidedReplica does not yet support copy data
• Meta-data not found for {block}
• The meta file length {metaIn.getLength()} is less than the e
• Replica of type ${getState()} does not support getOriginalRe

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