{"record":{"id":"fcd9d783cc5559cd","repo":"apache/hadoop","slug":"unexpected-configuration-parameters-dfs-namenode","errorCode":null,"errorMessage":"Unexpected configuration parameters: dfs.namenode.replication.min = {minR} <= 0","messagePattern":"Unexpected configuration parameters: dfs\\.namenode\\.replication\\.min = (.+?) <= 0","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":631,"sourceCode":"    this.deleteCorruptReplicaImmediately =\n        conf.getBoolean(DFS_NAMENODE_CORRUPT_BLOCK_DELETE_IMMEDIATELY_ENABLED,\n            DFS_NAMENODE_CORRUPT_BLOCK_DELETE_IMMEDIATELY_ENABLED_DEFAULT);\n\n    setExcessRedundancyTimeout(conf.getLong(DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_SEC_KEY,\n        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_SEC_DEAFULT));\n    setExcessRedundancyTimeoutCheckLimit(conf.getLong(\n        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_CHECK_LIMIT,\n        DFS_NAMENODE_EXCESS_REDUNDANCY_TIMEOUT_CHECK_LIMIT_DEFAULT));\n\n    printInitialConfigs();\n  }\n\n  private int initMinReplication(Configuration conf) throws IOException {\n    final int minR = conf.getInt(\n        DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY,\n        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 + \" > \"","sourceCodeStart":613,"sourceCodeEnd":649,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L613-L649","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set dfs.namenode.replication.min to a positive integer (1 is the default and almost always correct)","Or simply remove the property so the default applies","Restart the NameNode and confirm startup completes past BlockManager initialization"],"exampleFix":"<!-- before -->\n<property><name>dfs.namenode.replication.min</name><value>0</value></property>\n\n<!-- after -->\n<property><name>dfs.namenode.replication.min</name><value>1</value></property>","handlingStrategy":"validation","validationCode":"static void validateReplicationConf(Configuration conf) throws IOException {\n  int minR = conf.getInt(DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_KEY, DFSConfigKeys.DFS_NAMENODE_REPLICATION_MIN_DEFAULT);\n  if (minR <= 0) throw new IOException(\"dfs.namenode.replication.min must be >= 1, got \" + minR);\n}","typeGuard":null,"tryCatchPattern":"catch (IOException e) { if (e.getMessage().contains(\"dfs.namenode.replication.min\")) failDeployment(e); else throw e; }","preventionTips":["Validate replication keys in config-management CI before rolling to NameNodes","Omit the property unless you truly need a non-default minimum"],"tags":["hdfs","namenode","configuration","replication","startup-check"],"backgroundTag":"invalid-configuration-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}