apache/hadoop · error · IOException

Unexpected configuration parameters: dfs.namenode.replicatio

Error message

Unexpected configuration parameters: dfs.namenode.replication.min = {minReplication} > dfs.replication.max = {maxR}

What it means

Cross-field validation in BlockManager.initMaxReplication at NameNode startup: dfs.namenode.replication.min must not exceed dfs.replication.max, otherwise IOException 'Unexpected configuration parameters: dfs.namenode.replication.min = A > dfs.replication.max = B' fails startup. Each key individually can be legal while the pair is not.

Source

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

        DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_DEFAULT);
    if (minR <= 0) {
      throw new IOException("Unexpected configuration parameters: "
          + DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY
          + " = " + minR + " <= 0");
    }
    return minR;
  }

  private int initMaxReplication(Configuration conf) throws IOException {
    final int maxR = conf.getInt(DFSConfigKeys.DFS_REPLICATION_MAX_KEY,
        DFSConfigKeys.DFS_REPLICATION_MAX_DEFAULT);
    if (maxR > Short.MAX_VALUE) {
      throw new IOException("Unexpected configuration parameters: "
          + DFSConfigKeys.DFS_REPLICATION_MAX_KEY
          + " = " + maxR + " > " + Short.MAX_VALUE);
    }
    if (minReplication > maxR) {
      throw new IOException("Unexpected configuration parameters: "
          + DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY
          + " = " + minReplication + " > "
          + DFSConfigKeys.DFS_REPLICATION_MAX_KEY
          + " = " + maxR);
    }
    return maxR;
  }

  private int initMinReplicationToBeInMaintenance(Configuration conf)
      throws IOException {
    final int minMaintenanceR = conf.getInt(
        DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY,
        DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);

    if (minMaintenanceR < 0) {
      throw new IOException("Unexpected configuration parameters: "
          + DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY
          + " = " + minMaintenanceR + " < 0");

View on GitHub (pinned to 2add963021)

Solutions

Align the pair: make dfs.namenode.replication.min <= dfs.replication.max (typically min 1-3, max at least your highest dfs.replication in use)
If unsure, remove both overrides and run with defaults
Restart the NameNode

Example fix

<!-- before -->
<property><name>dfs.namenode.replication.min</name><value>5</value></property>
<property><name>dfs.replication.max</name><value>3</value></property>

<!-- after -->
<property><name>dfs.namenode.replication.min</name><value>1</value></property>
<property><name>dfs.replication.max</name><value>3</value></property>

Defensive patterns

Strategy: validation

Validate before calling

int minR = conf.getInt(DFS_NAMENODE_REPLICATION_MIN_KEY, DFS_NAMENODE_REPLICATION_MIN_DEFAULT);
int maxR = conf.getInt(DFS_REPLICATION_MAX_KEY, DFS_REPLICATION_MAX_DEFAULT);
if (minR > maxR) throw new IOException("dfs.namenode.replication.min (" + minR + ") must be <= dfs.replication.max (" + maxR + ")");

Try / catch

catch (IOException e) { if (e.getMessage().contains("replication.min") && e.getMessage().contains("replication.max")) failDeployment(e); else throw e; }

Prevention

Always review replication min/max together in one change; never tune one in isolation
Assert the pair invariant in pre-deploy config tests

When it happens

Trigger: hdfs-site.xml with dfs.namenode.replication.min=5 and dfs.replication.max=3 (or defaults overridden so min > max), then starting the NameNode.

Common situations: Tuning one key without checking the other; merging config fragments from different clusters; setting dfs.replication.max low for a test namespace while leaving a high min from a production template.

Related errors

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