apache/hadoop · error · UnsupportedOperationException

ProvidedReplica does not support deleting metadata

Error message

ProvidedReplica does not support deleting metadata

What it means

ProvidedReplica (ProvidedReplica.java:53) is the ReplicaInfo implementation for HDFS provided storage (HDFS-9140): a DataNode serves block bytes from an external, read-only store referenced by URI/FileRegion instead of local disks. Its checksum 'metadata' is a synthesized NULL_CHECKSUM_ARRAY, not a real meta file. deleteMetadata() therefore unconditionally throws UnsupportedOperationException because the DataNode has no authority to delete anything in the external store.

Source

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

  public long getBlockDataLength() {
    return this.getNumBytes();
  }

  @Override
  public LengthInputStream getMetadataInputStream(long offset)
      throws IOException {
    return new LengthInputStream(new ByteArrayInputStream(NULL_CHECKSUM_ARRAY),
        NULL_CHECKSUM_ARRAY.length);
  }

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

View on GitHub (pinned to 2add963021)

Solutions

Guard the call: skip deleteMetadata() when replica instanceof ProvidedReplica (or volume is a ProvidedVolumeImpl); provided replicas are read-only references.
Keep deletion/invalidation logic scoped to local volumes only; never point block-deletion utilities at provided storage.
If you subclass ProvidedReplica with a genuinely writable backend, override deleteMetadata() to implement the delete.
As a last-resort boundary, catch UnsupportedOperationException and log-and-skip rather than crashing the cleanup loop.

Example fix

// before
replica.deleteMetadata();

// after
if (!(replica instanceof ProvidedReplica)) {
  replica.deleteMetadata();
} else {
  LOG.debug("Skipping metadata delete for PROVIDED replica {}", replica.getBlockId());
}

Defensive patterns

Strategy: validation

Validate before calling

if (replica instanceof ProvidedReplica) {
  LOG.debug("Skipping metadata delete for PROVIDED replica {}", replica.getBlockId());
} else {
  replica.deleteMetadata();
}

Type guard

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

Try / catch

try {
  replica.deleteMetadata();
} catch (UnsupportedOperationException e) {
  LOG.warn("Replica {} is read-only provided storage: {}",
      replica.getBlockId(), e.getMessage());
}

Prevention

Treat every PROVIDED volume as read-only; audit all mutating ReplicaInfo calls in your code path.
Filter provided replicas/volumes before deletion, rename, copy, and pinning operations.
Keep a type-check helper (instanceof ProvidedReplica) and use it consistently in generic block tooling.

When it happens

Trigger: Calling ReplicaInfo.deleteMetadata() on a ProvidedReplica or FinalizedProvidedReplica instance. This happens when block-invalidation cleanup, directory-scanner reconciliation, or hand-written DataNode test/util code obtains a replica living on a PROVIDED volume (FsVolumeImpl replaced by ProvidedVolumeImpl) and tries to purge its .meta sidecar like a local replica.

Common situations: A cluster or test has a PROVIDED entry in dfs.datanode.data.dir (e.g. [ProvidedVolumeFactory]) with dfs.provided.alias-map configured, while code, cleanup tooling, or unit tests still assume every replica is a local-disk FinalizedReplica with deletable metadata.

Related errors

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