apache/hadoop · critical · IllegalArgumentException

Configured cluster topology should be org.apache.hadoop.net.

Error message

Configured cluster topology should be org.apache.hadoop.net.NetworkTopologyWithNodeGroup

What it means

Thrown by BlockPlacementPolicyWithNodeGroup.initialize when this placement policy is configured (net.topology.script.file.path / dfs.namenode.block-placement-policy or equivalent pointing at the NodeGroup-aware policy) but the cluster NetworkTopology object is not NetworkTopologyWithNodeGroup. The node-group policy requires node-group-aware topology because its replica choices depend on a third hierarchy level (node group) between rack and node.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockPlacementPolicyWithNodeGroup.java:50

 * The replica placement strategy is adjusted to:
 * If the writer is on a datanode, the 1st replica is placed on the local 
 *     node(or local node-group or on local rack), otherwise a random datanode.
 * The 2nd replica is placed on a datanode that is on a different rack with 1st
 *     replica node. 
 * The 3rd replica is placed on a datanode which is on a different node-group
 *     but the same rack as the second replica node.
 */
public class BlockPlacementPolicyWithNodeGroup extends BlockPlacementPolicyDefault {

  protected BlockPlacementPolicyWithNodeGroup() {
  }

  @Override
  public void initialize(Configuration conf,  FSClusterStats stats,
          NetworkTopology clusterMap, 
          Host2NodesMap host2datanodeMap) {
    if (!(clusterMap instanceof NetworkTopologyWithNodeGroup)) {
      throw new IllegalArgumentException(
          "Configured cluster topology should be "
              + NetworkTopologyWithNodeGroup.class.getName());
    }
    super.initialize(conf, stats, clusterMap, host2datanodeMap);
  }

  /**
   * choose all good favored nodes as target.
   * If no enough targets, then choose one replica from
   * each bad favored node's node group.
   * @throws NotEnoughReplicasException
   */
  @Override
  protected void chooseFavouredNodes(String src, int numOfReplicas,
      List<DatanodeDescriptor> favoredNodes,
      Set<Node> favoriteAndExcludedNodes, long blocksize,
      int maxNodesPerRack, List<DatanodeStorageInfo> results,
      boolean avoidStaleNodes, EnumMap<StorageType, Integer> storageTypes)

View on GitHub (pinned to 2add963021)

Solutions

1. Make topology consistent with the policy: configure the topology implementation as org.apache.hadoop.net.NetworkTopologyWithNodeGroup (e.g., -Dnet.topology.impl=...WithNodeGroup or the distro's equivalent topology config)
2. Or switch back to the default policy (BlockPlacementPolicyDefault) if node groups are not used
3. Search all active configs (hdfs-site.xml, core-site.xml, env-injected -D props) for block-placement and topology keys and align them
4. Restart NameNode after the change; verify with startup logs that the policy initialized

Example fix

<!-- before: policy without matching topology -->
<property><name>dfs.blockplacement.policy</name>
  <value>org.apache.hadoop.hdfs.server.blockmanagement.BlockPlacementPolicyWithNodeGroup</value></property>
<!-- topology stays plain NetworkTopology -> IllegalArgumentException -->

<!-- after: align topology implementation -->
<property><name>net.topology.impl</name>
  <value>org.apache.hadoop.net.NetworkTopologyWithNodeGroup</value></property>

// Startup config check (run before NN start)
Class<?> topo = Class.forName(conf.get("net.topology.impl", "org.apache.hadoop.net.NetworkTopology"));
Class<?> policy = Class.forName(conf.get("dfs.blockplacement.policy",
    "org.apache.hadoop.hdfs.server.blockmanagement.BlockPlacementPolicyDefault"));
if (policy.getSimpleName().contains("WithNodeGroup")
    && !topo.getName().endsWith("NetworkTopologyWithNodeGroup")) {
  throw new IllegalStateException("Set net.topology.impl=NetworkTopologyWithNodeGroup");
}

When it happens

Trigger: Config selects BlockPlacementPolicyWithNodeGroup (e.g., via dfs.blockplacement.policy or reflection in vendor distros) while dfs.namenode.network-topology / net.topology.impl defaults to plain NetworkTopology (or NetworkTopologyWithRack); mismatched topology configuration between the placement policy class and the topology implementation class.

Common situations: Porting cluster configs between vanilla Apache Hadoop and node-group-aware distros; setting a node-group placement policy without also setting the node-group topology implementation; leftover legacy config after an upgrade.

Related errors

• Failed to add {}: You cannot have a rack and a non-rack node
• Balancer without BlockPlacementPolicyDefault
• Unable to create the Decommission monitor from {cls}
• Unresolved topology mapping for host {hostname}
• Can not create a Path from a null string

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