{"record":{"id":"7e02d223fcdd6deb","repo":"apache/hadoop","slug":"balancer-without-blockplacementpolicydefault","errorCode":null,"errorMessage":"Balancer without BlockPlacementPolicyDefault","messagePattern":"Balancer without BlockPlacementPolicyDefault","errorType":"validation","errorClass":"UnsupportedActionException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java","lineNumber":267,"sourceCode":"\n  // all data node lists\n  private final Collection<Source> overUtilized = new LinkedList<Source>();\n  private final Collection<Source> aboveAvgUtilized = new LinkedList<Source>();\n  private final Collection<StorageGroup> belowAvgUtilized\n      = new LinkedList<StorageGroup>();\n  private final Collection<StorageGroup> underUtilized\n      = new LinkedList<StorageGroup>();\n\n  /* Check that this Balancer is compatible with the Block Placement Policy\n   * used by the Namenode.\n   */\n  private static void checkReplicationPolicyCompatibility(Configuration conf\n      ) throws UnsupportedActionException {\n    BlockPlacementPolicies placementPolicies =\n        new BlockPlacementPolicies(conf, null, NetworkTopology.getInstance(conf), null);\n    if (!(placementPolicies.getPolicy(CONTIGUOUS) instanceof\n        BlockPlacementPolicyDefault)) {\n      throw new UnsupportedActionException(\n          \"Balancer without BlockPlacementPolicyDefault\");\n    }\n  }\n\n  static long getLong(Configuration conf, String key, long defaultValue) {\n    final long v = conf.getLong(key, defaultValue);\n    LOG.info(key + \" = \" + v + \" (default=\" + defaultValue + \")\");\n    if (v <= 0) {\n      throw new HadoopIllegalArgumentException(key + \" = \" + v  + \" <= \" + 0);\n    }\n    return v;\n  }\n\n  static long getLongBytes(Configuration conf, String key, long defaultValue) {\n    final long v = conf.getLongBytes(key, defaultValue);\n    LOG.info(key + \" = \" + v + \" (default=\" + defaultValue + \")\");\n    if (v <= 0) {\n      throw new HadoopIllegalArgumentException(key + \" = \" + v  + \" <= \" + 0);","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java#L249-L285","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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","Run the balancer with a separate --config directory whose hdfs-site.xml has no custom policy setting","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"],"exampleFix":"// before (hdfs-site.xml used by the balancer)\n<property><name>dfs.block.replicator.classname</name><value>com.myco.hdfs.MyPlacementPolicy</value></property>\n\n// after: delete the property, or pin the default policy\n<property><name>dfs.block.replicator.classname</name><value>org.apache.hadoop.hdfs.server.blockmanagement.BlockPlacementPolicyDefault</value></property>","handlingStrategy":"validation","validationCode":"private static boolean balancerCompatible(Configuration conf) {\n  BlockPlacementPolicies policies =\n      new BlockPlacementPolicies(conf, null, NetworkTopology.getInstance(conf), null);\n  return policies.getPolicy(BlockPlacementPolicy.CONTIGUOUS)\n      instanceof BlockPlacementPolicyDefault;\n}\n// call before new Balancer(...).run()\nif (!balancerCompatible(conf)) { logAndAbort(\"Balancer requires BlockPlacementPolicyDefault\"); }","typeGuard":null,"tryCatchPattern":"catch (UnsupportedActionException e) { log.error(\"Placement policy incompatible with balancer: {}\", e.getMessage()); System.exit(-1); }","preventionTips":["Keep a dedicated, known-good hdfs-site.xml for ops tools like the balancer","Document any dfs.block.replicator.classname override in change management so operators know balancer runs will fail","Add a pre-flight check in balancer wrapper scripts using the validation helper above"],"tags":["hdfs","balancer","block-placement","configuration","startup-check"],"backgroundTag":"unsupported-configuration-combo","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}