{"record":{"id":"b2f3f60deed1b641","repo":"apache/hadoop","slug":"providedreplica-does-not-support-pinning","errorCode":null,"errorMessage":"ProvidedReplica does not support pinning","messagePattern":"ProvidedReplica does not support pinning","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ProvidedReplica.java","lineNumber":289,"sourceCode":"  public boolean renameMeta(URI destURI) throws IOException {\n    throw new UnsupportedOperationException(\n        \"ProvidedReplica does not support renaming metadata\");\n  }\n\n  @Override\n  public boolean renameData(URI destURI) throws IOException {\n    throw new UnsupportedOperationException(\n        \"ProvidedReplica does not support renaming data\");\n  }\n\n  @Override\n  public boolean getPinning(LocalFileSystem localFS) throws IOException {\n    return false;\n  }\n\n  @Override\n  public void setPinning(LocalFileSystem localFS) throws IOException {\n    throw new UnsupportedOperationException(\n        \"ProvidedReplica does not support pinning\");\n  }\n\n  @Override\n  public void bumpReplicaGS(long newGS) throws IOException {\n    throw new UnsupportedOperationException(\n        \"ProvidedReplica does not yet support writes\");\n  }\n\n  @Override\n  public boolean breakHardLinksIfNeeded() throws IOException {\n    return false;\n  }\n\n  @Override\n  public ReplicaRecoveryInfo createInfo()\n      throws UnsupportedOperationException {\n    throw new UnsupportedOperationException(","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ProvidedReplica.java#L271-L307","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Filter by volume/replica type before pinning: skip setPinning for ProvidedReplica or PROVIDED volumes.","Do not set the pinning flag on files whose blocks are (or will be) served from provided storage.","Patch the caller (e.g. FsDataset code or tooling) to consult volume.getAvailableSpace()/supported operations or instanceof before setPinning.","Catch UnsupportedOperationException in generic pinning loops and continue with a warning."],"exampleFix":"// before\nreplica.setPinning(localFS);\n\n// after\nif (!(replica instanceof ProvidedReplica)) {\n  replica.setPinning(localFS);\n}","handlingStrategy":"validation","validationCode":"if (!(replica instanceof ProvidedReplica)) {\n  replica.setPinning(localFS);\n} // getPinning() already reports false for provided replicas","typeGuard":"static boolean isProvided(ReplicaInfo r) {\n  return r instanceof ProvidedReplica;\n}","tryCatchPattern":"try {\n  replica.setPinning(localFS);\n} catch (UnsupportedOperationException e) {\n  LOG.warn(\"Pinning not supported for PROVIDED replica {}: {}\",\n      replica.getBlockId(), e.getMessage());\n}","preventionTips":["Do not set the create-time pinning flag for files on provided storage.","Filter by volume type in cluster-wide pin/unpin tooling.","Provided replicas are inherently non-evictable via local mechanisms; pinning them is meaningless."],"tags":["hdfs","datanode","provided-storage","pinning","read-only"],"backgroundTag":"unsupported-operation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}