apache/hadoop · error · IllegalArgumentException

Incompatible fromReplica state: {}

Error message

Incompatible fromReplica state: {}

What it means

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.

Source

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

    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);
      } else {
        if (length != -1) {
          return new ReplicaBeingWritten(blockId, length, genStamp,
              volume, directoryUsed, writer, bytesToReserve);
        } else {
          return new ReplicaBeingWritten(blockId, genStamp, volume,
              directoryUsed, bytesToReserve);
        }
      }

View on GitHub (pinned to 2add963021)

Solutions

1. Pass a from() replica whose getState() is RBW, matching the builder state.
2. Or drop from() entirely and construct fresh: setBlock+setWriterThread, or setBlockId/setGenerationStamp/setLength/setFsVolume/setDirectoryToUse/setWriterThread.
3. Validate fromReplica state before building and fail fast with a clear message.
4. Log both states (requested vs fromReplica) when the check fails to speed diagnosis.

Example fix

// before
ReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();

// after
Preconditions.checkArgument(source.getState() == ReplicaState.RBW,
    "from() replica must be RBW, got %s", source.getState());
ReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();

Preconditions.checkArgument(
    source == null || source.getState() == ReplicaState.RBW,
    "from() replica must be RBW, got %s",
    source == null ? null : source.getState());
ReplicaInfo r = new ReplicaBuilder(ReplicaState.RBW).from(source).buildLocalReplicaInPipeline();

static boolean fromReplicaMatches(ReplicaInfo source, ReplicaState target) {
  return source != null && source.getState() == target;
}

try {
  r = builder.buildLocalReplicaInPipeline();
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("RBW construction failed (state mismatch): "
      + e.getMessage(), e);
}

When it happens

Trigger: new ReplicaBuilder(ReplicaState.RBW).from(someReplica).buildLocalReplicaInPipeline() where someReplica.getState() != ReplicaState.RBW - e.g. passing a FinalizedReplica or ReplicaWaitingToBeRecovered as the from-source.

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

Related errors

• A valid writer is required for constructing a RBW from block
• Unknown replica state {}
• 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/f14bc4b53aa8cb29. Report an issue: GitHub.