{"record":{"id":"dfe3d90c9fbabd8b","repo":"apache/hadoop","slug":"providedreplica-does-not-support-renaming-metadata","errorCode":null,"errorMessage":"ProvidedReplica does not support renaming metadata","messagePattern":"ProvidedReplica does not support renaming metadata","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":272,"sourceCode":"  @Override\n  public boolean metadataExists() {\n    return NULL_CHECKSUM_ARRAY == null ? false : true;\n  }\n\n  @Override\n  public boolean deleteMetadata() {\n    throw new UnsupportedOperationException(\n        \"ProvidedReplica does not support deleting metadata\");\n  }\n\n  @Override\n  public long getMetadataLength() {\n    return NULL_CHECKSUM_ARRAY == null ? 0 : NULL_CHECKSUM_ARRAY.length;\n  }\n\n  @Override\n  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\");","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ProvidedReplica.java#L254-L290","documentation":"ProvidedReplica represents a replica whose bytes and checksums live in an external provided store; there is no local meta file to move. renameMeta(URI) unconditionally throws UnsupportedOperationException because renaming metadata inside the remote/read-only backing store is outside the DataNode contract.","triggerScenarios":"Invoking renameMeta(destURI) on a ProvidedReplica - typically via generic block-relocation code (finalize/recovery paths or test utilities that shuffle replicas between URIs) that was written against LocalReplica and calls renameMeta while migrating a block.","commonSituations":"Provided storage enabled (PROVIDED volume in dfs.datanode.data.dir) while an upgrade, recovery drill, or custom FsDataset extension attempts standard file-shuffle semantics on provided replicas; also hit in unit tests that build ProvidedReplica objects and exercise the full ReplicaInfo API surface.","solutions":["Check instanceof ProvidedReplica (or ReplicaState/ProvidedVolume) before renameMeta and skip the move for provided replicas.","Route block moves to local volumes only; provided replicas are pinned to their remote URI by design.","Override renameMeta in a writable ProvidedReplica subclass only if your backend truly supports it.","Catch UnsupportedOperationException at the migration boundary and treat that replica as immovable."],"exampleFix":"// before\nboolean moved = replica.renameMeta(destUri);\n\n// after\nboolean moved = (replica instanceof ProvidedReplica)\n    ? false\n    : replica.renameMeta(destUri);","handlingStrategy":"validation","validationCode":"if (!(replica instanceof ProvidedReplica)) {\n  replica.renameMeta(destUri);\n} // provided replicas: nothing to rename, skip silently or log","typeGuard":"static boolean isProvided(ReplicaInfo r) {\n  return r instanceof ProvidedReplica;\n}","tryCatchPattern":"try {\n  replica.renameMeta(destUri);\n} catch (UnsupportedOperationException e) {\n  LOG.warn(\"Cannot rename metadata of PROVIDED replica {}: {}\",\n      replica.getBlockId(), e.getMessage());\n}","preventionTips":["Never target provided replicas with file-shuffle (rename) logic.","Scope migration code to local volumes by checking the volume type up front.","Unit-test generic replica code against both local and provided replica types."],"tags":["hdfs","datanode","provided-storage","read-only","rename"],"backgroundTag":"unsupported-operation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}