apache/hadoop · error · IOException

Requested replication factor of {replication}{err} for {src}

Error message

Requested replication factor of {replication}{err} for {src}, clientName={clientName}

What it means

Thrown by BlockManager.verifyReplication when a create/append request specifies a replication factor outside the configured bounds: greater than dfs.namenode.max.replication (default 512) or less than dfs.namenode.min.replication (default 1). The NameNode enforces these limits because replication below min gives no durability and above max explodes block metadata and datanode load.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java:1718

   *
   * @param src the path to the target file
   * @param replication the requested replication factor
   * @param clientName the name of the client node making the request
   * @throws java.io.IOException thrown if the requested replication factor
   * is out of bounds
   */
   public void verifyReplication(String src,
                          short replication,
                          String clientName) throws IOException {
    String err = null;
    if (replication > maxReplication) {
      err = " exceeds maximum of " + maxReplication;
    } else if (replication < minReplication) {
      err = " is less than the required minimum of " + minReplication;
    }

    if (err != null) {
      throw new IOException("Requested replication factor of " + replication
          + err + " for " + src
          + (clientName == null? "": ", clientName=" + clientName));
    }
  }

  /**
   * Check if a block is replicated to at least the minimum replication.
   */
  public boolean isSufficientlyReplicated(BlockInfo b) {
    // Compare against the lesser of the minReplication and number of live DNs.
    final int liveReplicas = countNodes(b).liveReplicas();
    if (hasMinStorage(b, liveReplicas)) {
      return true;
    }
    // getNumLiveDataNodes() is very expensive and we minimize its use by
    // comparing with minReplication first.
    return liveReplicas >= getDatanodeManager().getNumLiveDataNodes();
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Set a valid replication factor: 1 <= replication <= 512, e.g. fs.create(path, (short) 3) or -Ddfs.replication=3
2. If intentional zero-replication for EC files, create the file with an ErasureCodingPolicy (FileSystem.create with EC flag) instead of replication=0
3. Check client-side hdfs-site.xml for dfs.replication and the NN's dfs.namenode.max.replication / dfs.namenode.min.replication if you need custom bounds
4. Validate/normalize the replication value in your code before passing it to FileSystem APIs (clamp to cluster defaults)

Example fix

// before: replication from unset config -> 0
short rep = Short.parseShort(conf.get("rep", "0"));
fs.create(path, rep, ...); // throws: less than required minimum of 1

// after: default to cluster default when unset
short rep = conf.getBoolean("rep.set", false)
    ? Short.parseShort(conf.get("rep"))
    : (short) conf.getInt("dfs.replication", 3);
if (rep < 1 || rep > 512) throw new IllegalArgumentException("rep out of range: " + rep);
fs.create(path, rep, ...);

short normalizeReplication(short requested, int clusterDefault, int min, int max) {
  if (requested <= 0) return (short) clusterDefault; // fill-in for unset config
  return (short) Math.max(min, Math.min(max, requested));
}
short rep = normalizeReplication(requested, conf.getInt("dfs.replication", 3), 1, 512);
fs.create(path, rep, true, 1 << 16, rep);

try {
  fs.create(path, rep);
} catch (IOException e) {
  if (e.getMessage().contains("replication factor")) {
    fs.create(path, (short) 3); // fall back to a valid default
  } else { throw e; }
}

When it happens

Trigger: ClientProtocol.create/append with replication parameter out of range: setReplication call, FileSystem.create(path, replication, ...) where replication < 1 or > maxReplication; tools reading a bad replication value from config or user input (e.g., -Ddfs.replication=0 or typo like 511+).

Common situations: Misconfigured dfs.replication=0 in client config; scripts passing replication from an unset variable (defaults to 0); users requesting very high replication exceeding 512; EC-era confusion where replication is set to 0 for striped files via wrong API path.

Related errors

• {key} = {v} <= 0
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.replication.max = {
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.namenode.maintenanc

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