apache/hadoop · error · IOException

Unexpected configuration parameters: dfs.namenode.replicatio

Error message

Unexpected configuration parameters: dfs.namenode.replication.min = {minR} <= 0

What it means

BlockManager.initMinReplication runs during NameNode startup and validates dfs.namenode.replication.min (default 1). The value must be >= 1, otherwise IOException 'Unexpected configuration parameters: dfs.namenode.replication.min = N <= 0' aborts NameNode initialization. Minimum replication is what keeps written blocks visible/safe, so zero is not a legal choice here.

Source

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

    this.deleteCorruptReplicaImmediately =
        conf.getBoolean(DFS_NAMENODE_CORRUPT_BLOCK_DELETE_IMMEDIATELY_ENABLED,
            DFS_NAMENODE_CORRUPT_BLOCK_DELETE_IMMEDIATELY_ENABLED_DEFAULT);

    setExcessRedundancyTimeout(conf.getLong(DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_SEC_KEY,
        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_SEC_DEAFULT));
    setExcessRedundancyTimeoutCheckLimit(conf.getLong(
        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_CHECK_LIMIT,
        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_CHECK_LIMIT_DEFAULT));

    printInitialConfigs();
  }

  private int initMinReplication(Configuration conf) throws IOException {
    final int minR = conf.getInt(
        DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY,
        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 + " > "

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.namenode.replication.min to a positive integer (1 is the default and almost always correct)
2. Or simply remove the property so the default applies
3. Restart the NameNode and confirm startup completes past BlockManager initialization

Example fix

<!-- before -->
<property><name>dfs.namenode.replication.min</name><value>0</value></property>

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

static void validateReplicationConf(Configuration conf) throws IOException {
  int minR = conf.getInt(DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY, DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_DEFAULT);
  if (minR <= 0) throw new IOException("dfs.namenode.replication.min must be >= 1, got " + minR);
}

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

When it happens

Trigger: Starting the NameNode with dfs.namenode.replication.min explicitly set to 0 or a negative number in hdfs-site.xml (or an XML substitution resolving to 0).

Common situations: Operators copying test-cluster configs where someone set it to 0; automation templating that emits 0 for 'use default' instead of omitting the property; misunderstanding the key as a boolean.

Related errors

• Unexpected configuration parameters: dfs.replication.max = {
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.namenode.maintenanc
• Unexpected configuration parameters: dfs.namenode.maintenanc
• Security is enabled but block access tokens (via dfs.block.a

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