apache/hadoop · error · IOException

Unexpected configuration parameters: dfs.namenode.maintenanc

Error message

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

What it means

BlockManager.initMinReplicationToBeInMaintenance validates dfs.namenode.maintenance.replication.min (default 0) at NameNode startup. Unlike the live-replication minimum, zero is legal here, but negative values are not: a negative value throws IOException 'Unexpected configuration parameters: dfs.namenode.maintenance.replication.min = N < 0' and aborts startup. This key controls how many replicas must remain while a node is in maintenance state.

Source

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

    }
    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");
    }
    if (minMaintenanceR > defaultReplication) {
      throw new IOException("Unexpected configuration parameters: "
          + DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY
          + " = " + minMaintenanceR + " > "
          + DFSConfigKeys.DFS_REPLICATION_KEY
          + " = " + defaultReplication);
    }
    return minMaintenanceR;
  }

  private int initReplQueueResetToHeadThreshold(Configuration conf) {
    int threshold = conf.getInt(
        DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS,
        DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS_DEFAULT);
    if (threshold < 0) {

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.namenode.maintenance.replication.min to 0 or a positive integer (0 = default, no replica requirement during maintenance)
2. Restart the NameNode

Example fix

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

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

int mM = conf.getInt(DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY, DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);
if (mM < 0) throw new IOException("dfs.namenode.maintenance.replication.min must be >= 0, got " + mM);

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

When it happens

Trigger: Starting the NameNode with dfs.namenode.maintenance.replication.min set to a negative integer (e.g. -1, sometimes used accidentally when templating or trying to 'disable' maintenance mode).

Common situations: Config templates with placeholder negatives; confusion between '0 = no maintenance replicas required' and '-1 = disabled'; copy-paste from another key's example.

Related errors

• Unexpected configuration parameters: dfs.namenode.maintenanc
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.replication.max = {
• Unexpected configuration parameters: dfs.namenode.replicatio
• 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/544ce5de0bf83054. Report an issue: GitHub.