{"record":{"id":"544ce5de0bf83054","repo":"apache/hadoop","slug":"unexpected-configuration-parameters-dfs-namenode-544ce5","errorCode":null,"errorMessage":"Unexpected configuration parameters: dfs.namenode.maintenance.replication.min = {minMaintenanceR} < 0","messagePattern":"Unexpected configuration parameters: dfs\\.namenode\\.maintenance\\.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":663,"sourceCode":"    }\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\");\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) {","sourceCodeStart":645,"sourceCodeEnd":681,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L645-L681","documentation":"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.","triggerScenarios":"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).","commonSituations":"Config templates with placeholder negatives; confusion between '0 = no maintenance replicas required' and '-1 = disabled'; copy-paste from another key's example.","solutions":["Set dfs.namenode.maintenance.replication.min to 0 or a positive integer (0 = default, no replica requirement during maintenance)","Restart the NameNode"],"exampleFix":"<!-- before -->\n<property><name>dfs.namenode.maintenance.replication.min</name><value>-1</value></property>\n\n<!-- after -->\n<property><name>dfs.namenode.maintenance.replication.min</name><value>0</value></property>","handlingStrategy":"validation","validationCode":"int mM = conf.getInt(DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_KEY, DFS_NAMENODE_MAINTENANCE_REPLICATION_MIN_DEFAULT);\nif (mM < 0) throw new IOException(\"dfs.namenode.maintenance.replication.min must be >= 0, got \" + mM);","typeGuard":null,"tryCatchPattern":"catch (IOException e) { if (e.getMessage().contains(\"maintenance.replication.min\")) failDeployment(e); else throw e; }","preventionTips":["Use 0 (the default) to express 'no maintenance replica requirement', never -1","Lint generated configs for negative numerics on replication keys"],"tags":["hdfs","namenode","configuration","maintenance","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"}