{"record":{"id":"c9f7a9a36c49d3a4","repo":"apache/hadoop","slug":"unexpected-configuration-parameters-dfs-namenode-c9f7a9","errorCode":null,"errorMessage":"Unexpected configuration parameters: dfs.namenode.replication.min = {minReplication} > dfs.replication.max = {maxR}","messagePattern":"Unexpected configuration parameters: dfs\\.namenode\\.replication\\.min = (.+?) > dfs\\.replication\\.max = (.+?)","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":647,"sourceCode":"        DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_DEFAULT);\n    if (minR <= 0) {\n      throw new IOException(\"Unexpected configuration parameters: \"\n          + DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY\n          + \" = \" + minR + \" <= 0\");\n    }\n    return minR;\n  }\n\n  private int initMaxReplication(Configuration conf) throws IOException {\n    final int maxR = conf.getInt(DFSConfigKeys.DFS_REPLICATION_MAX_KEY,\n        DFSConfigKeys.DFS_REPLICATION_MAX_DEFAULT);\n    if (maxR > Short.MAX_VALUE) {\n      throw new IOException(\"Unexpected configuration parameters: \"\n          + DFSConfigKeys.DFS_REPLICATION_MAX_KEY\n          + \" = \" + maxR + \" > \" + Short.MAX_VALUE);\n    }\n    if (minReplication > maxR) {\n      throw new IOException(\"Unexpected configuration parameters: \"\n          + DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY\n          + \" = \" + minReplication + \" > \"\n          + 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\");","sourceCodeStart":629,"sourceCodeEnd":665,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L629-L665","documentation":"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.","triggerScenarios":"hdfs-site.xml with dfs.namenode.replication.min=5 and dfs.replication.max=3 (or defaults overridden so min > max), then starting the NameNode.","commonSituations":"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.","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"],"exampleFix":"<!-- before -->\n<property><name>dfs.namenode.replication.min</name><value>5</value></property>\n<property><name>dfs.replication.max</name><value>3</value></property>\n\n<!-- after -->\n<property><name>dfs.namenode.replication.min</name><value>1</value></property>\n<property><name>dfs.replication.max</name><value>3</value></property>","handlingStrategy":"validation","validationCode":"int minR = conf.getInt(DFS_NAMENODE_REPLICATION_MIN_KEY, DFS_NAMENODE_REPLICATION_MIN_DEFAULT);\nint maxR = conf.getInt(DFS_REPLICATION_MAX_KEY, DFS_REPLICATION_MAX_DEFAULT);\nif (minR > maxR) throw new IOException(\"dfs.namenode.replication.min (\" + minR + \") must be <= dfs.replication.max (\" + maxR + \")\");","typeGuard":null,"tryCatchPattern":"catch (IOException e) { if (e.getMessage().contains(\"replication.min\") && e.getMessage().contains(\"replication.max\")) failDeployment(e); else throw e; }","preventionTips":["Always review replication min/max together in one change; never tune one in isolation","Assert the pair invariant in pre-deploy config tests"],"tags":["hdfs","namenode","configuration","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"}