apache/hadoop · error · DisallowedDatanodeException

Datanode denied communication with namenode because the host

Error message

Datanode denied communication with namenode because the host is not in the include-list: {nodeinfo}

What it means

Thrown as DisallowedDatanodeException when a DataNode heartbeats to the NameNode while its DatanodeDescriptor is marked disallowed; DatanodeManager first calls setDatanodeDead(nodeinfo) and then rejects the node (DatanodeManager.java:1871-1874). A node becomes disallowed by failing the include-list check that also guards registration (DatanodeManager.java:1213-1215, hostConfigManager.isIncluded), and the exception's default message is exactly 'the host is not in the include-list' (DisallowedDatanodeException.java:46). In effect the NameNode administratively bars the DataNode from the cluster.

Source

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

  /** Handle heartbeat from datanodes. */
  public DatanodeCommand[] handleHeartbeat(DatanodeRegistration nodeReg,
      StorageReport[] reports, final String blockPoolId,
      long cacheCapacity, long cacheUsed, int xceiverCount,
      int xmitsInProgress, int failedVolumes,
      VolumeFailureSummary volumeFailureSummary,
      @Nonnull SlowPeerReports slowPeers,
      @Nonnull SlowDiskReports slowDisks) throws IOException {
    final DatanodeDescriptor nodeinfo;
    try {
      nodeinfo = getDatanode(nodeReg);
    } catch (UnregisteredNodeException e) {
      return new DatanodeCommand[]{RegisterCommand.REGISTER};
    }

    // Check if this datanode should actually be shutdown instead.
    if (nodeinfo != null && nodeinfo.isDisallowed()) {
      setDatanodeDead(nodeinfo);
      throw new DisallowedDatanodeException(nodeinfo);
    }

    if (nodeinfo == null || !nodeinfo.isRegistered()) {
      return new DatanodeCommand[]{RegisterCommand.REGISTER};
    }
    heartbeatManager.updateHeartbeat(nodeinfo, reports, cacheCapacity,
        cacheUsed, xceiverCount, failedVolumes, volumeFailureSummary);

    // If we are in safemode, do not send back any recovery / replication
    // requests. Don't even drain the existing queue of work.
    if (namesystem.isInSafeMode()) {
      return new DatanodeCommand[0];
    }

    // block recovery command
    final BlockRecoveryCommand brCommand = getBlockRecoveryCommand(blockPoolId,
        nodeinfo);
    if (brCommand != null) {

View on GitHub (pinned to 2add963021)

Solutions

1. Add the DataNode's address exactly as the NameNode reports it in the {nodeinfo} log line (host and IP) to the dfs.hosts include file
2. Run 'hdfs dfsadmin -refreshNodes' so the NameNode reloads the include/exclude files
3. Verify forward and reverse DNS for the DataNode matches the include entries (or list both FQDN and IP in dfs.hosts)
4. Restart the DataNode process if it has backed off and stopped retrying registration
5. If exclusion was intentional, treat this as expected: complete the decommission and retire or fix the node, then remove it from the lists

Example fix

# before: dfs.hosts contains only
datanode101
# DN registers as datanode101.example.com -> denied

# after
datanode101
datanode101.example.com
# then: hdfs dfsadmin -refreshNodes

// preflight before starting/re-registering a DataNode
String inc = conf.get("dfs.hosts");
String dnAddr = dnReg.getIpAddr() != null ? dnReg.getIpAddr() : dnReg.getHostName();
if (inc != null) {
  List<String> allowed = Files.readAllLines(Paths.get(inc));
  if (allowed.stream().noneMatch(l -> l.trim().equals(dnAddr))) {
    throw new IllegalStateException("DN " + dnAddr + " not in dfs.hosts; add it and run -refreshNodes");
  }
}

try {
  dns.register(namenode, dnRegistration);
} catch (DisallowedDatanodeException e) {
  // administrative denial: do NOT retry in a tight loop
  LOG.error("Node disallowed by include-list; fix dfs.hosts and run hdfs dfsadmin -refreshNodes", e);
  scheduleReRegisterWithBackoff(); // or halt for operator action
}

When it happens

Trigger: A DataNode sends a heartbeat or registration RPC and its host/IP entry is absent from the file configured via dfs.hosts (or is filtered out via dfs.hosts.exclude), typically right after the include file was edited or 'hdfs dfsadmin -refreshNodes' ran. Also triggered when the DN registers with an address (FQDN vs short name, NAT/multi-homed IP) that does not string-match an include-file entry.

Common situations: Operators add or remove nodes and forget -refreshNodes; include file lists short hostnames while the DN registers with its FQDN (or vice versa); a new DataNode is installed while dfs.hosts is set but not updated; reverse-DNS of the DN's RPC source address resolves differently from the include entry.

Related errors

• Cannot lock storage {root}. The directory is already locked
• Incompatible node types: storageType={storageType} but Stora
• " + idHelpText + " mismatch: previously connected to " + idH
• No services to connect, missing NameNode address.
• Block pool {bpid} has not recognized an active NN

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