apache/hadoop · error · IllegalArgumentException

Finalized PROVIDED replica cannot be constructed from anothe

Error message

Finalized PROVIDED replica cannot be constructed from another replica

What it means

ReplicaBuilder.buildProvidedFinalizedReplica() creates a provided replica purely from addressing data (a FileRegion, a URI, or path prefix+suffix resolved against the remote filesystem). It throws IllegalArgumentException when from(replica) is supplied: a PROVIDED finalized replica references immutable external data and cannot be derived from another replica object.

Source

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

          "Missing a valid replica to recover from");
    }
    if (null != writer || null != block) {
      throw new IllegalArgumentException("Invalid state for "
          + "recovering from replica with blk id "
          + fromReplica.getBlockId());
    }
    if (fromReplica.getState() == ReplicaState.RUR) {
      return new ReplicaUnderRecovery((ReplicaUnderRecovery) fromReplica);
    } else {
      return new ReplicaUnderRecovery(fromReplica, recoveryId);
    }
  }

  private ProvidedReplica buildProvidedFinalizedReplica()
      throws IllegalArgumentException {
    ProvidedReplica info = null;
    if (fromReplica != null) {
      throw new IllegalArgumentException("Finalized PROVIDED replica " +
          "cannot be constructed from another replica");
    }
    if (fileRegion == null && uri == null &&
        (pathPrefix == null || pathSuffix == null)) {
      throw new IllegalArgumentException(
          "Trying to construct a provided replica on " + volume +
          " without enough information");
    }
    if (fileRegion == null) {
      if (uri != null) {
        info = new FinalizedProvidedReplica(blockId, uri, offset,
            length, genStamp, pathHandle, volume, conf, remoteFS);
      } else {
        info = new FinalizedProvidedReplica(blockId, pathPrefix, pathSuffix,
            offset, length, genStamp, pathHandle, volume, conf, remoteFS);
      }
    } else {
      info = new FinalizedProvidedReplica(fileRegion, volume, conf, remoteFS);

View on GitHub (pinned to 2add963021)

Solutions

Drop .from(...) and supply provided addressing instead: setFileRegion(fr), or setURI+offset+length(+setPathHandle/setRemoteFS/setConf), or setPathPrefix+setPathSuffix.
Ensure at least one addressing source is set - otherwise the builder fails its 'without enough information' check.
Route conversions the other way (provided to local) by reading the remote bytes into local storage, not by rebuilding replica objects.
Keep provided-replica construction in a dedicated factory that never accepts a from-replica.

Example fix

// before
ProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)
    .from(localReplica)
    .setFsVolume(providedVolume).build();

// after
ProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)
    .setFileRegion(fileRegion)
    .setFsVolume(providedVolume)
    .setConf(conf).build();

Defensive patterns

Strategy: validation

Validate before calling

Preconditions.checkState(source == null,
    "PROVIDED finalized replicas cannot derive from another replica; "
    + "supply setFileRegion / setURI / setPathPrefix+setPathSuffix");
ProvidedReplica r = new ReplicaBuilder(ReplicaState.PROVIDED)
    .setFileRegion(fileRegion)
    .setFsVolume(providedVolume)
    .setConf(conf).build();

Try / catch

try {
  r = (ProvidedReplica) builder.build();
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("PROVIDED replica construction failed: "
      + e.getMessage(), e);
}

Prevention

Build PROVIDED replicas only from addressing data (FileRegion, URI+offset, prefix+suffix).
Isolate provided-replica construction in its own factory that never accepts from().
To materialize provided data locally, copy the bytes; do not rebuild replica objects.

When it happens

Trigger: new ReplicaBuilder(ReplicaState.PROVIDED).from(source).build() (or the provided-finalized path) - any attempt to convert an existing local/other replica into a provided one through the builder.

Common situations: Generic conversion code that routes every replica state through a from(replica) chain; tests that build PROVIDED replicas by copying a template replica; refactors where the provided path was added to an existing from()-based factory.

Related errors

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