{"record":{"id":"32f7f315bd234950","repo":"apache/hadoop","slug":"unexpected-configuration-parameters-dfs-namenode-32f7f3","errorCode":null,"errorMessage":"Unexpected configuration parameters: dfs.namenode.maintenance.replication.min = {minMaintenanceR} > dfs.replication = {defaultReplication}","messagePattern":"Unexpected configuration parameters: dfs\\.namenode\\.maintenance\\.replication\\.min = (.+?) > dfs\\.replication = (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java","lineNumber":668,"sourceCode":"          + DFSConfigKeys.DFS_REPLICATION_MAX_KEY\n          + \" = \" + maxR);\n    }\n    return maxR;\n  }\n\n  private int initMinReplicationToBeInMaintenance(Configuration conf)\n      throws IOException {\n    final int minMaintenanceR = conf.getInt(\n        DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY,\n        DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);\n\n    if (minMaintenanceR < 0) {\n      throw new IOException(\"Unexpected configuration parameters: \"\n          + DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY\n          + \" = \" + minMaintenanceR + \" < 0\");\n    }\n    if (minMaintenanceR > defaultReplication) {\n      throw new IOException(\"Unexpected configuration parameters: \"\n          + DFSConfigKeys.DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY\n          + \" = \" + minMaintenanceR + \" > \"\n          + DFSConfigKeys.DFS_REPLICATION_KEY\n          + \" = \" + defaultReplication);\n    }\n    return minMaintenanceR;\n  }\n\n  private int initReplQueueResetToHeadThreshold(Configuration conf) {\n    int threshold = conf.getInt(\n        DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS,\n        DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS_DEFAULT);\n    if (threshold < 0) {\n      LOG.warn(\"{} is set to {} and it must be >= 0. Resetting to default {}\",\n          DFSConfigKeys.DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS,\n          threshold, DFSConfigKeys.\n              DFS_NAMENODE_REDUNDANCY_QUEUE_RESTART_ITERATIONS_DEFAULT);\n      threshold = DFSConfigKeys.","sourceCodeStart":650,"sourceCodeEnd":686,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L650-L686","documentation":"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.","triggerScenarios":"hdfs-site.xml with dfs.namenode.maintenance.replication.min=4 while dfs.replication=3 (explicitly or by default), then starting the NameNode.","commonSituations":"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.","solutions":["Lower dfs.namenode.maintenance.replication.min to <= dfs.replication","Or raise dfs.replication (and ensure dfs.replication.max accommodates it) if the higher maintenance minimum is intentional","Restart the NameNode"],"exampleFix":"<!-- before -->\n<property><name>dfs.namenode.maintenance.replication.min</name><value>4</value></property>\n<property><name>dfs.replication</name><value>3</value></property>\n\n<!-- after -->\n<property><name>dfs.namenode.maintenance.replication.min</name><value>2</value></property>\n<property><name>dfs.replication</name><value>3</value></property>","handlingStrategy":"validation","validationCode":"int mM = conf.getInt(DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY, DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);\nint defRepl = (int) conf.getLongBytes(DFS_REPLICATION_KEY, DFS_REPLICATION_DEFAULT);\nif (mM > defRepl) throw new IOException(\"maintenance min \" + mM + \" exceeds dfs.replication \" + defRepl);","typeGuard":null,"tryCatchPattern":"catch (IOException e) { if (e.getMessage().contains(\"maintenance.replication.min\") && e.getMessage().contains(\"dfs.replication\")) failDeployment(e); else throw e; }","preventionTips":["When changing dfs.replication or maintenance minimums, validate all three replication keys as a set","Keep maintenance min <= default replication in config templates by construction"],"tags":["hdfs","namenode","configuration","maintenance","replication","cross-field-validation","startup-check"],"backgroundTag":"conflicting-configuration-values","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}