{"record":{"id":"f14bc4b53aa8cb29","repo":"apache/hadoop","slug":"incompatible-fromreplica-state","errorCode":null,"errorMessage":"Incompatible fromReplica state: {}","messagePattern":"Incompatible fromReplica 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":207,"sourceCode":"    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);\n      } else {\n        if (length != -1) {\n          return new ReplicaBeingWritten(blockId, length, genStamp,\n              volume, directoryUsed, writer, bytesToReserve);\n        } else {\n          return new ReplicaBeingWritten(blockId, genStamp, volume,\n              directoryUsed, bytesToReserve);\n        }\n      }","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java#L189-L225","documentation":"ReplicaBuilder.buildRBW() builds a ReplicaBeingWritten. If a source replica is supplied via from(replica) but its own state is not RBW, the builder throws IllegalArgumentException 'Incompatible fromReplica state' - you cannot derive an RBW (being-written) replica from, say, a FINALIZED or RWR replica.","triggerScenarios":"new ReplicaBuilder(ReplicaState.RBW).from(someReplica).buildLocalReplicaInPipeline() where someReplica.getState() != ReplicaState.RBW - e.g. passing a FinalizedReplica or ReplicaWaitingToBeRecovered as the from-source.","commonSituations":"Refactoring write-path code that converts between replica kinds, or tests that grab whatever replica is handy and feed it to the builder without checking its state; state drifted after recovery/finalization races.","solutions":["Pass a from() replica whose getState() is RBW, matching the builder state.","Or drop from() entirely and construct fresh: setBlock+setWriterThread, or setBlockId/setGenerationStamp/setLength/setFsVolume/setDirectoryToUse/setWriterThread.","Validate fromReplica state before building and fail fast with a clear message.","Log both states (requested vs fromReplica) when the check fails to speed diagnosis."],"exampleFix":"// before\nReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();\n\n// after\nPreconditions.checkArgument(source.getState() == ReplicaState.RBW,\n    \"from() replica must be RBW, got %s\", source.getState());\nReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();","handlingStrategy":"validation","validationCode":"Preconditions.checkArgument(\n    source == null || source.getState() == ReplicaState.RBW,\n    \"from() replica must be RBW, got %s\",\n    source == null ? null : source.getState());\nReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();","typeGuard":"static boolean fromReplicaMatches(ReplicaInfo source, ReplicaState target) {\n  return source != null && source.getState() == target;\n}","tryCatchPattern":"try {\n  r = builder.buildLocalReplicaInPipeline();\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"RBW construction failed (state mismatch): \"\n      + e.getMessage(), e);\n}","preventionTips":["Always pair the builder's target state with from()'s replica state.","Re-read the source replica's state immediately before building.","Fail fast on state mismatch instead of relying on the builder's late check."],"tags":["hdfs","datanode","replica","builder","rbw"],"backgroundTag":"builder-state-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}