apache/hadoop · error · UnsupportedOperationException

ProvidedReplica does not support pinning

Error message

ProvidedReplica does not support pinning

What it means

HDFS replica pinning (setPinning) records a pinned flag on the local replica so it is not evicted/moved. ProvidedReplica.getPinning() returns false by design, but setPinning unconditionally throws UnsupportedOperationException because a provided replica is served from immutable external storage the DataNode cannot annotate.

Source

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

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

  @Override
  public boolean breakHardLinksIfNeeded() throws IOException {
    return false;
  }

  @Override
  public ReplicaRecoveryInfo createInfo()
      throws UnsupportedOperationException {
    throw new UnsupportedOperationException(

View on GitHub (pinned to 2add963021)

Solutions

1. Filter by volume/replica type before pinning: skip setPinning for ProvidedReplica or PROVIDED volumes.
2. Do not set the pinning flag on files whose blocks are (or will be) served from provided storage.
3. Patch the caller (e.g. FsDataset code or tooling) to consult volume.getAvailableSpace()/supported operations or instanceof before setPinning.
4. Catch UnsupportedOperationException in generic pinning loops and continue with a warning.

Example fix

// before
replica.setPinning(localFS);

// after
if (!(replica instanceof ProvidedReplica)) {
  replica.setPinning(localFS);
}

if (!(replica instanceof ProvidedReplica)) {
  replica.setPinning(localFS);
} // getPinning() already reports false for provided replicas

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

try {
  replica.setPinning(localFS);
} catch (UnsupportedOperationException e) {
  LOG.warn("Pinning not supported for PROVIDED replica {}: {}",
      replica.getBlockId(), e.getMessage());
}

When it happens

Trigger: A client creates/appends a file with the pinning flag set (create(..., setPinning) / unpin-pin flows), or test code calls setPinning directly, and the target replica is a ProvidedReplica on a PROVIDED volume - the FsDataset write path then invokes setPinning on it.

Common situations: Pin-enabled HDFS deployments (lazy persist / eviction-avoidance workflows, HDFS-14511 pinned replicas) combined with provided storage mounts; also custom tooling that pins all replicas cluster-wide without filtering by volume type.

Related errors

• ProvidedReplica does not support deleting metadata
• ProvidedReplica does not support renaming metadata
• ProvidedReplica does not support renaming data
• 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/b2f3f60deed1b641. Report an issue: GitHub.