apache/hadoop · error · IllegalArgumentException

A valid writer is required for constructing a RBW from block

Error message

A valid writer is required for constructing a RBW from block {}

What it means

When ReplicaBuilder constructs a ReplicaBeingWritten from a Block (setBlock) rather than from an existing replica, it requires a live writer thread (setWriterThread) - the RBW replica tracks the thread writing its bytes for interruption/monitoring. If writer is null it throws IllegalArgumentException 'A valid writer is required for constructing a RBW from block'.

Source

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

    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);
        }
      }
    }
  }

  private LocalReplicaInPipeline buildTemporaryReplica()
      throws IllegalArgumentException {

View on GitHub (pinned to 2add963021)

Solutions

1. Add .setWriterThread(Thread.currentThread()) (or the actual writer thread) before build when using setBlock.
2. Alternatively build from raw fields (setBlockId/setGenerationStamp/setFsVolume/setDirectoryToUse/setWriterThread/setBytesToReserved) instead of setBlock - the writer is still required for in-pipeline replicas.
3. Fail fast in your wrapper: assert writer is set before invoking the builder.

Example fix

// before
LocalReplicaInPipeline r = new ReplicaBuilder(ReplicaState.RBW)
    .setBlock(block).buildLocalReplicaInPipeline();

// after
LocalReplicaInPipeline r = new ReplicaBuilder(ReplicaState.RBW)
    .setBlock(block)
    .setWriterThread(Thread.currentThread())
    .buildLocalReplicaInPipeline();

if (block != null && writer == null) {
  throw new IllegalStateException(
      "setWriterThread is required when building an RBW from a Block");
}
LocalReplicaInPipeline r = new ReplicaBuilder(ReplicaState.RBW)
    .setBlock(block)
    .setWriterThread(Thread.currentThread())
    .buildLocalReplicaInPipeline();

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

When it happens

Trigger: new ReplicaBuilder(ReplicaState.RBW).setBlock(block).buildLocalReplicaInPipeline() without a prior .setWriterThread(...) call - the block branch of buildRBW() finds a null writer and throws.

Common situations: Test code or refactored DataNode write paths that build RBW replicas from a Block object but forget the writer thread; copied code from finalized-replica construction where no writer is needed.

Related errors

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

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