{"record":{"id":"846b7d75c35b9f47","repo":"apache/hadoop","slug":"finalized-provided-replica-cannot-be-constructed-f","errorCode":null,"errorMessage":"Finalized PROVIDED replica cannot be constructed from another replica","messagePattern":"Finalized PROVIDED replica cannot be constructed from another replica","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java","lineNumber":315,"sourceCode":"          \"Missing a valid replica to recover from\");\n    }\n    if (null != writer || null != block) {\n      throw new IllegalArgumentException(\"Invalid state for \"\n          + \"recovering from replica with blk id \"\n          + fromReplica.getBlockId());\n    }\n    if (fromReplica.getState() == ReplicaState.RUR) {\n      return new ReplicaUnderRecovery((ReplicaUnderRecovery) fromReplica);\n    } else {\n      return new ReplicaUnderRecovery(fromReplica, recoveryId);\n    }\n  }\n\n  private ProvidedReplica buildProvidedFinalizedReplica()\n      throws IllegalArgumentException {\n    ProvidedReplica info = null;\n    if (fromReplica != null) {\n      throw new IllegalArgumentException(\"Finalized PROVIDED replica \" +\n          \"cannot be constructed from another replica\");\n    }\n    if (fileRegion == null && uri == null &&\n        (pathPrefix == null || pathSuffix == null)) {\n      throw new IllegalArgumentException(\n          \"Trying to construct a provided replica on \" + volume +\n          \" without enough information\");\n    }\n    if (fileRegion == null) {\n      if (uri != null) {\n        info = new FinalizedProvidedReplica(blockId, uri, offset,\n            length, genStamp, pathHandle, volume, conf, remoteFS);\n      } else {\n        info = new FinalizedProvidedReplica(blockId, pathPrefix, pathSuffix,\n            offset, length, genStamp, pathHandle, volume, conf, remoteFS);\n      }\n    } else {\n      info = new FinalizedProvidedReplica(fileRegion, volume, conf, remoteFS);","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java#L297-L333","documentation":"ReplicaBuilder.buildProvidedFinalizedReplica() creates a provided replica purely from addressing data (a FileRegion, a URI, or path prefix+suffix resolved against the remote filesystem). It throws IllegalArgumentException when from(replica) is supplied: a PROVIDED finalized replica references immutable external data and cannot be derived from another replica object.","triggerScenarios":"new ReplicaBuilder(ReplicaState.PROVIDED).from(source).build() (or the provided-finalized path) - any attempt to convert an existing local/other replica into a provided one through the builder.","commonSituations":"Generic conversion code that routes every replica state through a from(replica) chain; tests that build PROVIDED replicas by copying a template replica; refactors where the provided path was added to an existing from()-based factory.","solutions":["Drop .from(...) and supply provided addressing instead: setFileRegion(fr), or setURI+offset+length(+setPathHandle/setRemoteFS/setConf), or setPathPrefix+setPathSuffix.","Ensure at least one addressing source is set - otherwise the builder fails its 'without enough information' check.","Route conversions the other way (provided to local) by reading the remote bytes into local storage, not by rebuilding replica objects.","Keep provided-replica construction in a dedicated factory that never accepts a from-replica."],"exampleFix":"// before\nProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)\n    .from(localReplica)\n    .setFsVolume(providedVolume).build();\n\n// after\nProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)\n    .setFileRegion(fileRegion)\n    .setFsVolume(providedVolume)\n    .setConf(conf).build();","handlingStrategy":"validation","validationCode":"Preconditions.checkState(source == null,\n    \"PROVIDED finalized replicas cannot derive from another replica; \"\n    + \"supply setFileRegion / setURI / setPathPrefix+setPathSuffix\");\nProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)\n    .setFileRegion(fileRegion)\n    .setFsVolume(providedVolume)\n    .setConf(conf).build();","typeGuard":null,"tryCatchPattern":"try {\n  r = (ProvidedReplica) builder.build();\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"PROVIDED replica construction failed: \"\n      + e.getMessage(), e);\n}","preventionTips":["Build PROVIDED replicas only from addressing data (FileRegion, URI+offset, prefix+suffix).","Isolate provided-replica construction in its own factory that never accepts from().","To materialize provided data locally, copy the bytes; do not rebuild replica objects."],"tags":["hdfs","datanode","replica","builder","provided-storage"],"backgroundTag":"builder-state-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}