apache/hadoop · error · HadoopIllegalArgumentException

Illegal configuration value for dfs.client.block.write.repla

Error message

Illegal configuration value for dfs.client.block.write.replace-datanode-on-failure.policy: ${policy}

What it means

ReplaceDatanodeOnFailure.get(Configuration) parses dfs.client.block.write.replace-datanode-on-failure.policy by matching the string case-insensitively against the Policy enum values, skipping DISABLE (values()[0], which is only produced when enable=false). Any string that is not DEFAULT, NEVER or ALWAYS throws HadoopIllegalArgumentException eagerly, before any cluster contact.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/datatransfer/ReplaceDatanodeOnFailure.java:170

  private static Policy getPolicy(final Configuration conf) {
    final boolean enabled = conf.getBoolean(
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.ENABLE_KEY,
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.ENABLE_DEFAULT);
    if (!enabled) {
      return Policy.DISABLE;
    }

    final String policy = conf.get(
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.POLICY_KEY,
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.POLICY_DEFAULT);
    for(int i = 1; i < Policy.values().length; i++) {
      final Policy p = Policy.values()[i];
      if (p.name().equalsIgnoreCase(policy)) {
        return p;
      }
    }
    throw new HadoopIllegalArgumentException("Illegal configuration value for "
        + HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.POLICY_KEY
        + ": " + policy);
  }

  /** Write the setting to configuration. */
  public static void write(final Policy policy,
      final boolean bestEffort, final Configuration conf) {
    conf.setBoolean(
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.ENABLE_KEY,
        policy != Policy.DISABLE);
    conf.set(
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.POLICY_KEY,
        policy.name());
    conf.setBoolean(
        HdfsClientConfigKeys.BlockWrite.ReplaceDatanodeOnFailure.BEST_EFFORT_KEY,
        bestEffort);
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Set the property to DEFAULT, NEVER or ALWAYS (case-insensitive), or delete it to fall back to the DEFAULT default
2. To disable the feature use dfs.client.block.write.replace-datanode-on-failure.enable=false - never policy=DISABLE
3. Re-check for typos and surrounding whitespace if the value looks correct

Example fix

<!-- before -->
<property>
  <name>dfs.client.block.write.replace-datanode-on-failure.policy</name>
  <value>DISABLE</value>
</property>

<!-- after: disabling is done via the enable flag -->
<property>
  <name>dfs.client.block.write.replace-datanode-on-failure.enable</name>
  <value>false</value>
</property>

String v = conf.getTrimmed(
    "dfs.client.block.write.replace-datanode-on-failure.policy", "DEFAULT");
Set<String> allowed = new HashSet<>(Arrays.asList("DEFAULT", "NEVER", "ALWAYS"));
if (!allowed.contains(v.toUpperCase(Locale.ROOT))) {
  throw new IllegalArgumentException(
      "Invalid replace-datanode-on-failure policy: " + v);
}

When it happens

Trigger: Setting dfs.client.block.write.replace-datanode-on-failure.policy to a value outside {DEFAULT, NEVER, ALWAYS}: the literal 'DISABLE' (invalid - disabling is done via the enable flag), typos like 'defualt', or stray whitespace. Fails on first use of the configuration in the client write path.

Common situations: Config template typos; users writing policy=DISABLE expecting to switch the feature off; copy-paste artifacts or XML entities introducing stray characters into the value.

Related errors

• Can not create a Path from a null string
• Can not create a Path from an empty string
• no SharedFileDescriptorFactory paths were configured.
• Failed to create ${basePath}[source=${source}, allow-append=
• Error connecting to file system: ${basePath} [${ex}]

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/515a579a4564a404. Report an issue: GitHub.