{"record":{"id":"15d334b673bdd994","repo":"apache/hadoop","slug":"unknown-replica-state","errorCode":null,"errorMessage":"Unknown replica state {}","messagePattern":"Unknown replica state (.+?)","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":198,"sourceCode":"  }\n\n  public ReplicaBuilder setLastPartialChunkChecksum(byte[] checksum) {\n    this.lastPartialChunkChecksum = checksum;\n    return this;\n  }\n\n  public LocalReplicaInPipeline buildLocalReplicaInPipeline()\n      throws IllegalArgumentException {\n    LocalReplicaInPipeline info = null;\n    switch(state) {\n    case RBW:\n      info = buildRBW();\n      break;\n    case TEMPORARY:\n      info = buildTemporaryReplica();\n      break;\n    default:\n      throw new IllegalArgumentException(\"Unknown replica state \" + state);\n    }\n    return info;\n  }\n\n  private LocalReplicaInPipeline buildRBW() throws IllegalArgumentException {\n    if (null != fromReplica && fromReplica.getState() == ReplicaState.RBW) {\n      return new ReplicaBeingWritten((ReplicaBeingWritten) fromReplica);\n    } else if (null != fromReplica) {\n      throw new IllegalArgumentException(\"Incompatible fromReplica \"\n          + \"state: \" + fromReplica.getState());\n    } else {\n      if (null != block) {\n        if (null == writer) {\n          throw new IllegalArgumentException(\"A valid writer is \"\n              + \"required for constructing a RBW from block \"\n              + block.getBlockId());\n        }\n        return new ReplicaBeingWritten(block, volume, directoryUsed, writer);","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java#L180-L216","documentation":"ReplicaBuilder.buildLocalReplicaInPipeline() constructs a LocalReplicaInPipeline (a replica being written) via a switch on ReplicaState that only handles RBW and TEMPORARY. Any other state (FINALIZED, RWR, RUR, PROVIDED) falls to default and throws IllegalArgumentException 'Unknown replica state'.","triggerScenarios":"Calling new ReplicaBuilder(state).buildLocalReplicaInPipeline() with state != RBW and != TEMPORARY, e.g. ReplicaState.FINALIZED. In-pipeline factories only make sense for replicas under construction, so finalized/recovered/provided states are rejected.","commonSituations":"Custom DataNode/FsDataset code or unit tests that reuse the builder generically and pass a state obtained dynamically (e.g. from an existing replica or config) straight into the in-pipeline factory without validating it.","solutions":["Only call buildLocalReplicaInPipeline() for RBW or TEMPORARY states; use the state-appropriate builder path (e.g. buildFinalizedReplica) for other states.","Validate the state before the call and fail fast with your own descriptive message.","If you need a LocalReplicaInPipeline from an arbitrary source replica, first convert/derive it into RBW/TEMPORARY semantics.","Add a unit test asserting which states your code path can produce."],"exampleFix":"// before\nLocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();\n\n// after\nPreconditions.checkArgument(\n    state == ReplicaState.RBW || state == ReplicaState.TEMPORARY,\n    \"buildLocalReplicaInPipeline requires RBW or TEMPORARY, got %s\", state);\nLocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();","handlingStrategy":"validation","validationCode":"if (state != ReplicaState.RBW && state != ReplicaState.TEMPORARY) {\n  throw new IllegalArgumentException(\n      \"buildLocalReplicaInPipeline requires RBW or TEMPORARY, got \" + state);\n}\nLocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();","typeGuard":"static boolean isPipelineState(ReplicaState s) {\n  return s == ReplicaState.RBW || s == ReplicaState.TEMPORARY;\n}","tryCatchPattern":"try {\n  r = builder.buildLocalReplicaInPipeline();\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\n      \"Builder misconfigured for in-pipeline construction: \" + e.getMessage(), e);\n}","preventionTips":["Map each ReplicaState to its dedicated builder path; do not reuse the in-pipeline factory generically.","Validate state enums before dispatching to state-specific factories.","Cover every state branch in unit tests of builder-based code."],"tags":["hdfs","datanode","replica","builder","validation"],"backgroundTag":"builder-state-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}