apache/hadoop · error · IOException

Unexpected configuration parameters: dfs.namenode.maintenanc

Error message

Unexpected configuration parameters: dfs.namenode.maintenance.replication.min = {minMaintenanceR} > dfs.replication = {defaultReplication}

What it means

Second check in BlockManager.initMinReplicationToBeInMaintenance at NameNode startup: dfs.namenode.maintenance.replication.min must not exceed dfs.replication (the default replication factor), otherwise IOException 'dfs.namenode.maintenance.replication.min = A > dfs.replication = B' aborts startup. Requesting more maintenance replicas than files have by default is contradictory, hence the fail-fast.

Source

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

          + 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) {
      LOG.warn("{} is set to {} and it must be >= 0. Resetting to default {}",
          DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS,
          threshold, DFSConfigKeys.
              DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS_DEFAULT);
      threshold = DFSConfigKeys.

View on GitHub (pinned to 2add963021)

Solutions

1. Lower dfs.namenode.maintenance.replication.min to <= dfs.replication
2. Or raise dfs.replication (and ensure dfs.replication.max accommodates it) if the higher maintenance minimum is intentional
3. Restart the NameNode

Example fix

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

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

int mM = conf.getInt(DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY, DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);
int defRepl = (int) conf.getLongBytes(DFS_REPLICATION_KEY, DFS_REPLICATION_DEFAULT);
if (mM > defRepl) throw new IOException("maintenance min " + mM + " exceeds dfs.replication " + defRepl);

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

When it happens

Trigger: hdfs-site.xml with dfs.namenode.maintenance.replication.min=4 while dfs.replication=3 (explicitly or by default), then starting the NameNode.

Common situations: Raising the maintenance minimum for strict maintenance policies without also considering the cluster default replication; inheriting a maintenance-heavy config onto a small test cluster with dfs.replication lowered.

Related errors

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