apache/hadoop · error · IOException

Only an ACTIVE node can invoke startCheckpoint.

Error message

Only an ACTIVE node can invoke startCheckpoint.

What it means

startCheckpoint on NamenodeProtocol is how a BackupNode/CheckpointNode drives checkpointing on the primary. After verifyRequest(registration) and the superuser check, the serving NameNode rejects the call with IOException('Only an ACTIVE node can invoke startCheckpoint.') unless nn.isRole(NamenodeRole.NAMENODE) - the process receiving the RPC must be a primary NameNode, not itself a BACKUP or CHECKPOINT role process. (ACTIVE and STANDBY in an HA pair both carry role NAMENODE; the guard specifically excludes backup/checkpoint-role processes.)

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNodeRpcServer.java:714

      NamenodeRegistration registration) throws IOException {
    String operationName = "registerSubordinateNamenode";
    checkNNStartup();
    namesystem.checkSuperuserPrivilege(operationName);
    verifyLayoutVersion(registration.getVersion());
    NamenodeRegistration myRegistration = nn.setRegistration();
    namesystem.registerBackupNode(registration, myRegistration);
    return myRegistration;
  }

  @Override // NamenodeProtocol
  public NamenodeCommand startCheckpoint(NamenodeRegistration registration)
      throws IOException {
    String operationName = "startCheckpoint";
    checkNNStartup();
    namesystem.checkSuperuserPrivilege(operationName);
    verifyRequest(registration);
    if(!nn.isRole(NamenodeRole.NAMENODE))
      throw new IOException("Only an ACTIVE node can invoke startCheckpoint.");

    CacheEntryWithPayload cacheEntry = getCacheEntryWithPayload(null);
    if (cacheEntry != null && cacheEntry.isSuccess()) {
      return (NamenodeCommand) cacheEntry.getPayload();
    }
    NamenodeCommand ret = null;
    try {
      ret = namesystem.startCheckpoint(registration, nn.setRegistration());
    } finally {
      RetryCache.setState(cacheEntry, ret != null, ret);
    }
    return ret;
  }

  /**
   * Return the current CacheEntry.
   */
  private CacheEntry getCacheEntry() {

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure the BackupNode/CheckpointNode targets the primary NameNode - its fs.defaultFS/service RPC address must point at the ACTIVE NameNode
2. Verify process roles on each host (`jps`: NameNode vs BackupNode/CheckpointNode) and restart any host wrongly started as backup/checkpoint
3. Keep exactly one primary NameNode for the namespace the backup node serves
4. If you only need periodic checkpoints without the backup protocol, run a SecondaryNameNode instead

Example fix

# before - both hosts started as checkpoint nodes; backup targets a non-primary
hdfs --daemon start checkpoint  # on nn1 AND nn2 by mistake

# after - one primary NameNode, checkpoint node points at it
hdfs --daemon start namenode    # on nn1 (active)
hdfs --daemon start checkpoint  # on nn2, with fs.defaultFS=nn1:8020

# Before relying on checkpoint RPCs, confirm the target is the primary
ROLE=$(hdfs haadmin -getServiceState nn1 2>/dev/null || echo unknown)
[ "$ROLE" = "active" ] || { echo "target nn1 is not active/primary"; exit 1; }

static boolean isPrimaryNameNode(NameNode nn) {
  return nn.isRole(NamenodeRole.NAMENODE); // excludes BACKUP/CHECKPOINT roles
}

catch (IOException e) {
  if (e.getMessage().contains("Only an ACTIVE node can invoke startCheckpoint")) {
    // re-point the BackupNode at the true primary and restart its checkpoint loop
  }
}

When it happens

Trigger: A BackupNode/CheckpointNode whose configured primary target is itself running as a BACKUP or CHECKPOINT role process - e.g. both nodes were started as backup/checkpoint nodes, or the backup node's target address points at another backup node instead of the active NameNode.

Common situations: Misconfigured checkpoint node topology (chaining backup nodes); scripts that start every NN host as CheckpointNode by mistake; failure of the primary leaving the backup pointing at a non-primary process.

Related errors

• No logs to roll forward from lastApplied
• Unexpected not positive size: {}
• Processing RPC request caught
• Unsupported protocol found when creating the proxy connectio
• The length of the feature flag section was negative at {} by

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