apache/hadoop · error · IllegalArgumentException

Unknown replica state {}

Error message

Unknown replica state {}

What it means

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'.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/ReplicaBuilder.java:198

  }

  public ReplicaBuilder setLastPartialChunkChecksum(byte[] checksum) {
    this.lastPartialChunkChecksum = checksum;
    return this;
  }

  public LocalReplicaInPipeline buildLocalReplicaInPipeline()
      throws IllegalArgumentException {
    LocalReplicaInPipeline info = null;
    switch(state) {
    case RBW:
      info = buildRBW();
      break;
    case TEMPORARY:
      info = buildTemporaryReplica();
      break;
    default:
      throw new IllegalArgumentException("Unknown replica state " + state);
    }
    return info;
  }

  private LocalReplicaInPipeline buildRBW() throws IllegalArgumentException {
    if (null != fromReplica && fromReplica.getState() == ReplicaState.RBW) {
      return new ReplicaBeingWritten((ReplicaBeingWritten) fromReplica);
    } else if (null != fromReplica) {
      throw new IllegalArgumentException("Incompatible fromReplica "
          + "state: " + fromReplica.getState());
    } else {
      if (null != block) {
        if (null == writer) {
          throw new IllegalArgumentException("A valid writer is "
              + "required for constructing a RBW from block "
              + block.getBlockId());
        }
        return new ReplicaBeingWritten(block, volume, directoryUsed, writer);

View on GitHub (pinned to 2add963021)

Solutions

1. Only call buildLocalReplicaInPipeline() for RBW or TEMPORARY states; use the state-appropriate builder path (e.g. buildFinalizedReplica) for other states.
2. Validate the state before the call and fail fast with your own descriptive message.
3. If you need a LocalReplicaInPipeline from an arbitrary source replica, first convert/derive it into RBW/TEMPORARY semantics.
4. Add a unit test asserting which states your code path can produce.

Example fix

// before
LocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();

// after
Preconditions.checkArgument(
    state == ReplicaState.RBW || state == ReplicaState.TEMPORARY,
    "buildLocalReplicaInPipeline requires RBW or TEMPORARY, got %s", state);
LocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();

if (state != ReplicaState.RBW && state != ReplicaState.TEMPORARY) {
  throw new IllegalArgumentException(
      "buildLocalReplicaInPipeline requires RBW or TEMPORARY, got " + state);
}
LocalReplicaInPipeline r = new ReplicaBuilder(state).buildLocalReplicaInPipeline();

static boolean isPipelineState(ReplicaState s) {
  return s == ReplicaState.RBW || s == ReplicaState.TEMPORARY;
}

try {
  r = builder.buildLocalReplicaInPipeline();
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException(
      "Builder misconfigured for in-pipeline construction: " + e.getMessage(), e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Incompatible fromReplica state: {}
• A valid writer is required for constructing a RBW from block
• A valid writer is required for constructing a Replica from b
• Missing a valid replica to recover from
• Invalid state for recovering from replica with blk id {}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/15d334b673bdd994. Report an issue: GitHub.