apache/hadoop · error · UnsupportedActionException

Balancer without BlockPlacementPolicyDefault

Error message

Balancer without BlockPlacementPolicyDefault

What it means

Thrown by Balancer.checkReplicationPolicyCompatibility before any move is scheduled. The balancer can only compute valid replica targets for the default contiguous placement policy (BlockPlacementPolicyDefault); it constructs a BlockPlacementPolicies from the configuration and rejects anything else via UnsupportedActionException. This is a fail-fast guard, not a transient condition - the balancer has no logic for custom placement policies.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java:267

  // all data node lists
  private final Collection<Source> overUtilized = new LinkedList<Source>();
  private final Collection<Source> aboveAvgUtilized = new LinkedList<Source>();
  private final Collection<StorageGroup> belowAvgUtilized
      = new LinkedList<StorageGroup>();
  private final Collection<StorageGroup> underUtilized
      = new LinkedList<StorageGroup>();

  /* Check that this Balancer is compatible with the Block Placement Policy
   * used by the Namenode.
   */
  private static void checkReplicationPolicyCompatibility(Configuration conf
      ) throws UnsupportedActionException {
    BlockPlacementPolicies placementPolicies =
        new BlockPlacementPolicies(conf, null, NetworkTopology.getInstance(conf), null);
    if (!(placementPolicies.getPolicy(CONTIGUOUS) instanceof
        BlockPlacementPolicyDefault)) {
      throw new UnsupportedActionException(
          "Balancer without BlockPlacementPolicyDefault");
    }
  }

  static long getLong(Configuration conf, String key, long defaultValue) {
    final long v = conf.getLong(key, defaultValue);
    LOG.info(key + " = " + v + " (default=" + defaultValue + ")");
    if (v <= 0) {
      throw new HadoopIllegalArgumentException(key + " = " + v  + " <= " + 0);
    }
    return v;
  }

  static long getLongBytes(Configuration conf, String key, long defaultValue) {
    final long v = conf.getLongBytes(key, defaultValue);
    LOG.info(key + " = " + v + " (default=" + defaultValue + ")");
    if (v <= 0) {
      throw new HadoopIllegalArgumentException(key + " = " + v  + " <= " + 0);

View on GitHub (pinned to 2add963021)

Solutions

1. Remove dfs.block.replicator.classname from hdfs-site.xml (or set it to org.apache.hadoop.hdfs.server.blockmanagement.BlockPlacementPolicyDefault) on the machine/gateway where the balancer runs, then rerun
2. Run the balancer with a separate --config directory whose hdfs-site.xml has no custom policy setting
3. If the cluster must keep the custom policy, use distcp or the Mover (for storage policies) to relocate data instead, or file a JIRA for balancer support of that policy

Example fix

// before (hdfs-site.xml used by the balancer)
<property><name>dfs.block.replicator.classname</name><value>com.myco.hdfs.MyPlacementPolicy</value></property>

// after: delete the property, or pin the default policy
<property><name>dfs.block.replicator.classname</name><value>org.apache.hadoop.hdfs.server.blockmanagement.BlockPlacementPolicyDefault</value></property>

private static boolean balancerCompatible(Configuration conf) {
  BlockPlacementPolicies policies =
      new BlockPlacementPolicies(conf, null, NetworkTopology.getInstance(conf), null);
  return policies.getPolicy(BlockPlacementPolicy.CONTIGUOUS)
      instanceof BlockPlacementPolicyDefault;
}
// call before new Balancer(...).run()
if (!balancerCompatible(conf)) { logAndAbort("Balancer requires BlockPlacementPolicyDefault"); }

catch (UnsupportedActionException e) { log.error("Placement policy incompatible with balancer: {}", e.getMessage()); System.exit(-1); }

When it happens

Trigger: Running 'hdfs balancer' (or new Balancer(...).run()) when the effective configuration resolves the CONTIGUOUS placement policy to a non-default class - typically because dfs.block.replicator.classname in hdfs-site.xml points to a custom policy (e.g. BlockPlacementPolicyRackFaultTolerant or an in-house class).

Common situations: Clusters using rack-fault-tolerant or vendor placement policies; hdfs-site.xml copied from another cluster during a merge; someone experimenting with placement policy settings then running the balancer with the same config directory.

Related errors

• {key} = {v} <= 0
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.replication.max = {
• Unexpected configuration parameters: dfs.namenode.replicatio
• Unexpected configuration parameters: dfs.namenode.maintenanc

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