{"record":{"id":"7920b006f2b9fba8","repo":"apache/hadoop","slug":"requested-replication-factor-of-replication-err","errorCode":null,"errorMessage":"Requested replication factor of {replication}{err} for {src}, clientName={clientName}","messagePattern":"Requested replication factor of (.+?)(.+?) for (.+?), clientName=(.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java","lineNumber":1718,"sourceCode":"   *\n   * @param src the path to the target file\n   * @param replication the requested replication factor\n   * @param clientName the name of the client node making the request\n   * @throws java.io.IOException thrown if the requested replication factor\n   * is out of bounds\n   */\n   public void verifyReplication(String src,\n                          short replication,\n                          String clientName) throws IOException {\n    String err = null;\n    if (replication > maxReplication) {\n      err = \" exceeds maximum of \" + maxReplication;\n    } else if (replication < minReplication) {\n      err = \" is less than the required minimum of \" + minReplication;\n    }\n\n    if (err != null) {\n      throw new IOException(\"Requested replication factor of \" + replication\n          + err + \" for \" + src\n          + (clientName == null? \"\": \", clientName=\" + clientName));\n    }\n  }\n\n  /**\n   * Check if a block is replicated to at least the minimum replication.\n   */\n  public boolean isSufficientlyReplicated(BlockInfo b) {\n    // Compare against the lesser of the minReplication and number of live DNs.\n    final int liveReplicas = countNodes(b).liveReplicas();\n    if (hasMinStorage(b, liveReplicas)) {\n      return true;\n    }\n    // getNumLiveDataNodes() is very expensive and we minimize its use by\n    // comparing with minReplication first.\n    return liveReplicas >= getDatanodeManager().getNumLiveDataNodes();\n  }","sourceCodeStart":1700,"sourceCodeEnd":1736,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockManager.java#L1700-L1736","documentation":"Thrown by BlockManager.verifyReplication when a create/append request specifies a replication factor outside the configured bounds: greater than dfs.namenode.max.replication (default 512) or less than dfs.namenode.min.replication (default 1). The NameNode enforces these limits because replication below min gives no durability and above max explodes block metadata and datanode load.","triggerScenarios":"ClientProtocol.create/append with replication parameter out of range: setReplication call, FileSystem.create(path, replication, ...) where replication < 1 or > maxReplication; tools reading a bad replication value from config or user input (e.g., -Ddfs.replication=0 or typo like 511+).","commonSituations":"Misconfigured dfs.replication=0 in client config; scripts passing replication from an unset variable (defaults to 0); users requesting very high replication exceeding 512; EC-era confusion where replication is set to 0 for striped files via wrong API path.","solutions":["Set a valid replication factor: 1 <= replication <= 512, e.g. fs.create(path, (short) 3) or -Ddfs.replication=3","If intentional zero-replication for EC files, create the file with an ErasureCodingPolicy (FileSystem.create with EC flag) instead of replication=0","Check client-side hdfs-site.xml for dfs.replication and the NN's dfs.namenode.max.replication / dfs.namenode.min.replication if you need custom bounds","Validate/normalize the replication value in your code before passing it to FileSystem APIs (clamp to cluster defaults)"],"exampleFix":"// before: replication from unset config -> 0\nshort rep = Short.parseShort(conf.get(\"rep\", \"0\"));\nfs.create(path, rep, ...); // throws: less than required minimum of 1\n\n// after: default to cluster default when unset\nshort rep = conf.getBoolean(\"rep.set\", false)\n    ? Short.parseShort(conf.get(\"rep\"))\n    : (short) conf.getInt(\"dfs.replication\", 3);\nif (rep < 1 || rep > 512) throw new IllegalArgumentException(\"rep out of range: \" + rep);\nfs.create(path, rep, ...);","handlingStrategy":"validation","validationCode":"short normalizeReplication(short requested, int clusterDefault, int min, int max) {\n  if (requested <= 0) return (short) clusterDefault; // fill-in for unset config\n  return (short) Math.max(min, Math.min(max, requested));\n}\nshort rep = normalizeReplication(requested, conf.getInt(\"dfs.replication\", 3), 1, 512);\nfs.create(path, rep, true, 1 << 16, rep);","typeGuard":null,"tryCatchPattern":"try {\n  fs.create(path, rep);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"replication factor\")) {\n    fs.create(path, (short) 3); // fall back to a valid default\n  } else { throw e; }\n}","preventionTips":["Validate replication in the range 1..512 before calling create/append/setReplication","Fail fast on unparseable replication config instead of defaulting to 0","For EC files use the EC-policy create path rather than replication=0","Document cluster min/max replication in deployment runbooks"],"tags":["hdfs","replication","configuration","file-create","validation"],"backgroundTag":"invalid-replication-factor","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}