{"record":{"id":"44c2ddc6c7f0afc1","repo":"apache/hadoop","slug":"unexpected-configuration-parameters-dfs-replicati","errorCode":null,"errorMessage":"Unexpected configuration parameters: dfs.replication.max = {maxR} > 32767","messagePattern":"Unexpected configuration parameters: dfs\\.replication\\.max = (.+?) > 32767","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":642,"sourceCode":"  }\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 + \" > \"\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);","sourceCodeStart":624,"sourceCodeEnd":660,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L624-L660","documentation":"BlockManager.initMaxReplication validates dfs.replication.max during NameNode startup. Replication factors are stored in a 16-bit signed field, so the maximum legal value is Short.MAX_VALUE = 32767; anything larger throws IOException 'Unexpected configuration parameters: dfs.replication.max = N > 32767' and the NameNode does not start.","triggerScenarios":"hdfs-site.xml sets dfs.replication.max above 32767 (e.g. 100000 or 2147483647), then the NameNode process is started.","commonSituations":"Someone 'removing the cap' by setting a huge number; global find-replace across config templates bumping replication values; confusion between max replication and an ID or port field.","solutions":["Set dfs.replication.max to 32767 or lower (values in the low hundreds are typical for real clusters)","Restart the NameNode"],"exampleFix":"<!-- before -->\n<property><name>dfs.replication.max</name><value>1000000</value></property>\n\n<!-- after -->\n<property><name>dfs.replication.max</name><value>32767</value></property>","handlingStrategy":"validation","validationCode":"int maxR = conf.getInt(DFSConfigKeys.DFS_REPLICATION_MAX_KEY, DFSConfigKeys.DFS_REPLICATION_MAX_DEFAULT);\nif (maxR > Short.MAX_VALUE) throw new IOException(\"dfs.replication.max must be <= 32767, got \" + maxR);","typeGuard":null,"tryCatchPattern":"catch (IOException e) { if (e.getMessage().contains(\"dfs.replication.max\")) failDeployment(e); else throw e; }","preventionTips":["Cap dfs.replication.max at a realistic ceiling (hundreds), never near 32767","Add a config lint rule rejecting replication keys above Short.MAX_VALUE"],"tags":["hdfs","namenode","configuration","replication","range-check","startup-check"],"backgroundTag":"invalid-configuration-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}