apache/hadoop · error · IllegalArgumentException

Trying to construct a provided replica on {} without enough

Error message

Trying to construct a provided replica on {} without enough information

What it means

ReplicaBuilder.buildProvidedFinalizedReplica() throws this IllegalArgumentException when a FINALIZED replica is being built on a PROVIDED storage volume but none of the three accepted data sources are set: a FileRegion, a remote URI, or a pathPrefix+pathSuffix pair. PROVIDED replicas do not store bytes locally; the builder needs at least one of these to describe where the data lives in the remote/external filesystem. This is a fail-fast guard so a meaningless ProvidedReplica is never constructed.

Source

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

          + 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);
    }
    return info;
  }

  private ProvidedReplica buildProvidedReplica()

View on GitHub (pinned to 2add963021)

Solutions

1. Set a FileRegion on the builder if you have blockId+path+offset+length+genStamp: .setFileRegion(new FileRegion(...))
2. Otherwise set a remote-file URI plus offset/length: .setURI(uri).setOffset(..).setLength(..).setRemoteFS(remoteFS)
3. Otherwise set BOTH .setPathPrefix(prefixPath) and .setPathSuffix(suffix)
4. If you meant to copy an existing local replica, note fromReplica is explicitly rejected for PROVIDED FINALIZED - build from the FileRegion of the provided store instead

Example fix

// before
ReplicaInfo r = new ReplicaBuilder(ReplicaState.FINALIZED)
    .setBlockId(bid).setGenerationStamp(gs).setLength(len)
    .setFsVolume(providedVolume)   // no FileRegion/URI/path
    .build();                      // IllegalArgumentException

// after
ReplicaInfo r = new ReplicaBuilder(ReplicaState.FINALIZED)
    .setBlockId(bid).setGenerationStamp(gs).setLength(len)
    .setFsVolume(providedVolume)
    .setFileRegion(new FileRegion(bp, bid, gs, remotePath, offset, len))
    .setRemoteFS(remoteFS)
    .build();

boolean canBuildProvidedFinalized(ReplicaBuilder b) {
  return b.getFileRegion() != null
      || b.getURI() != null
      || (b.getPathPrefix() != null && b.getPathSuffix() != null);
}
// call before .build() when volume.getStorageType() == StorageType.PROVIDED

try { replica = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("without enough information")) { /* re-populate FileRegion/URI and rebuild */ } else throw e; }

When it happens

Trigger: Calling new ReplicaBuilder(ReplicaState.FINALIZED).setFsVolume(providedVolume)...build() where the volume's StorageType is PROVIDED, fromReplica is null, and none of setFileRegion(), setURI(), or both setPathPrefix(Path)+setPathSuffix(String) were called. build() routes to buildProvidedReplica() -> buildProvidedFinalizedReplica() and the fileRegion==null && uri==null && (pathPrefix==null || pathSuffix==null) guard fires.

Common situations: Writing a ProvidedStorageContext/FsDatasetSpi integration or unit tests for HDFS-9140 provided storage and forgetting to seed the builder with a FileRegion or URI; deserializing replicas from a PROVIDED volume's replica file where only the blockId/genStamp were parsed; setting pathPrefix without pathSuffix (or vice versa).

Related errors

• Finalized PROVIDED replica cannot be constructed from anothe
• Unknown replica state {} for PROVIDED replica
• Replica of type ${getState()} does not support getOriginalRe
• Unknown replica state {}
• Incompatible fromReplica state: {}

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