{"record":{"id":"dbcb0104313831cd","repo":"apache/hadoop","slug":"unknown-replica-state-for-provided-replica","errorCode":null,"errorMessage":"Unknown replica state {} for PROVIDED replica","messagePattern":"Unknown replica state (.+?) for PROVIDED 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":350,"sourceCode":"    } else {\n      info = new FinalizedProvidedReplica(fileRegion, volume, conf, remoteFS);\n    }\n    return info;\n  }\n\n  private ProvidedReplica buildProvidedReplica()\n      throws IllegalArgumentException {\n    ProvidedReplica info = null;\n    switch(this.state) {\n    case FINALIZED:\n      info = buildProvidedFinalizedReplica();\n      break;\n    case RWR:\n    case RUR:\n    case RBW:\n    case TEMPORARY:\n    default:\n      throw new IllegalArgumentException(\"Unknown replica state \" +\n          state + \" for PROVIDED replica\");\n    }\n    return info;\n  }\n\n  private LocalReplica buildLocalReplica()\n      throws IllegalArgumentException {\n    LocalReplica info = null;\n    switch(this.state) {\n    case FINALIZED:\n      info = buildFinalizedReplica();\n      break;\n    case RWR:\n      info = buildRWR();\n      break;\n    case RUR:\n      info = buildRUR();\n      break;","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java#L332-L368","documentation":"When ReplicaBuilder.build() targets a volume whose StorageType is PROVIDED, it delegates to buildProvidedReplica(), which only supports ReplicaState.FINALIZED. Any of RWR, RUR, RBW, TEMPORARY (or a state added later that hits default) throws IllegalArgumentException because provided replicas are immutable references into an external filesystem - they can never be in a write pipeline or under recovery on the DataNode.","triggerScenarios":"new ReplicaBuilder(ReplicaState.RBW) (or RWR/RUR/TEMPORARY) followed by .setFsVolume(volume) where volume.getStorageType()==StorageType.PROVIDED, then .build(). The switch in buildProvidedReplica() falls through to the default branch and throws.","commonSituations":"Generic replica-handling code that was written for local disks being reused unchanged on a PROVIDED volume (e.g., block recovery or RBW append paths hitting provided storage); tests that build replicas in RBW state against a ProvidedVolume; misconfigured dfs.datanode.data.dir mixing PROVIDED with write workloads that expect local replicas.","solutions":["Use ReplicaState.FINALIZED whenever the target volume is a PROVIDED volume","Branch on volume.getStorageType() before building: only call the builder with non-FINALIZED states for local (DISK/ARCHIVE etc.) volumes","If a write pipeline genuinely needs storage, move the replica to a local volume instead of PROVIDED"],"exampleFix":"// before\nReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW)\n    .setFsVolume(providedVolume).build(); // throws for PROVIDED\n\n// after\nReplicaInfo r;\nif (volume.getStorageType() == StorageType.PROVIDED) {\n  r = new ReplicaBuilder(ReplicaState.FINALIZED)\n      .setFsVolume(volume).setFileRegion(region).build();\n} else {\n  r = new ReplicaBuilder(ReplicaState.RBW).setFsVolume(volume).build();\n}","handlingStrategy":"validation","validationCode":"if (volume.getStorageType() == StorageType.PROVIDED\n    && state != ReplicaState.FINALIZED) {\n  throw new IllegalStateException(\n      \"PROVIDED volume only supports FINALIZED replicas, got \" + state);\n}\nReplicaInfo r = new ReplicaBuilder(state).setFsVolume(volume).build();","typeGuard":"static boolean isProvided(FsVolumeSpi v) {\n  return v != null && v.getStorageType() == StorageType.PROVIDED;\n}","tryCatchPattern":"try { builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"for PROVIDED replica\")) { state = ReplicaState.FINALIZED; /* rebuild */ } else throw e; }","preventionTips":["Treat PROVIDED volumes as read-only references: only FINALIZED is legal","Write tests that build each ReplicaState against both local and PROVIDED volumes"],"tags":["hdfs","datanode","provided-storage","replica","state-machine","illegal-argument"],"backgroundTag":"invalid-enum-state","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}