{"record":{"id":"0a077119ae453e90","repo":"apache/hadoop","slug":"only-an-active-node-can-invoke-startcheckpoint","errorCode":null,"errorMessage":"Only an ACTIVE node can invoke startCheckpoint.","messagePattern":"Only an ACTIVE node can invoke startCheckpoint\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNodeRpcServer.java","lineNumber":714,"sourceCode":"      NamenodeRegistration registration) throws IOException {\n    String operationName = \"registerSubordinateNamenode\";\n    checkNNStartup();\n    namesystem.checkSuperuserPrivilege(operationName);\n    verifyLayoutVersion(registration.getVersion());\n    NamenodeRegistration myRegistration = nn.setRegistration();\n    namesystem.registerBackupNode(registration, myRegistration);\n    return myRegistration;\n  }\n\n  @Override // NamenodeProtocol\n  public NamenodeCommand startCheckpoint(NamenodeRegistration registration)\n      throws IOException {\n    String operationName = \"startCheckpoint\";\n    checkNNStartup();\n    namesystem.checkSuperuserPrivilege(operationName);\n    verifyRequest(registration);\n    if(!nn.isRole(NamenodeRole.NAMENODE))\n      throw new IOException(\"Only an ACTIVE node can invoke startCheckpoint.\");\n\n    CacheEntryWithPayload cacheEntry = getCacheEntryWithPayload(null);\n    if (cacheEntry != null && cacheEntry.isSuccess()) {\n      return (NamenodeCommand) cacheEntry.getPayload();\n    }\n    NamenodeCommand ret = null;\n    try {\n      ret = namesystem.startCheckpoint(registration, nn.setRegistration());\n    } finally {\n      RetryCache.setState(cacheEntry, ret != null, ret);\n    }\n    return ret;\n  }\n\n  /**\n   * Return the current CacheEntry.\n   */\n  private CacheEntry getCacheEntry() {","sourceCodeStart":696,"sourceCodeEnd":732,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNodeRpcServer.java#L696-L732","documentation":"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.)","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the BackupNode/CheckpointNode targets the primary NameNode - its fs.defaultFS/service RPC address must point at the ACTIVE NameNode","Verify process roles on each host (`jps`: NameNode vs BackupNode/CheckpointNode) and restart any host wrongly started as backup/checkpoint","Keep exactly one primary NameNode for the namespace the backup node serves","If you only need periodic checkpoints without the backup protocol, run a SecondaryNameNode instead"],"exampleFix":"# before - both hosts started as checkpoint nodes; backup targets a non-primary\nhdfs --daemon start checkpoint  # on nn1 AND nn2 by mistake\n\n# after - one primary NameNode, checkpoint node points at it\nhdfs --daemon start namenode    # on nn1 (active)\nhdfs --daemon start checkpoint  # on nn2, with fs.defaultFS=nn1:8020","handlingStrategy":"try-catch","validationCode":"# Before relying on checkpoint RPCs, confirm the target is the primary\nROLE=$(hdfs haadmin -getServiceState nn1 2>/dev/null || echo unknown)\n[ \"$ROLE\" = \"active\" ] || { echo \"target nn1 is not active/primary\"; exit 1; }","typeGuard":"static boolean isPrimaryNameNode(NameNode nn) {\n  return nn.isRole(NamenodeRole.NAMENODE); // excludes BACKUP/CHECKPOINT roles\n}","tryCatchPattern":"catch (IOException e) {\n  if (e.getMessage().contains(\"Only an ACTIVE node can invoke startCheckpoint\")) {\n    // re-point the BackupNode at the true primary and restart its checkpoint loop\n  }\n}","preventionTips":["Configure the BackupNode/CheckpointNode's target (fs.defaultFS) to the ACTIVE NameNode and keep it in sync after failovers","Audit `jps` on each NN host: exactly one primary NameNode per namespace, others explicitly backup/checkpoint","Consider SecondaryNameNode when the in-memory backup protocol is not required","Add a startup smoke test that calls versionRequest against the intended primary"],"tags":["hdfs","name-node","backup-node","checkpoint","rpc","namenode-protocol"],"backgroundTag":"checkpoint-role-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}