apache/hadoop · warning · RetriableException

Namenode is in startup mode

Error message

Namenode is in startup mode

What it means

NameNode.queueExternalCall throws RetriableException('Namenode is in startup mode') when rpcServer is still null: the NameNode object exists but startCommonServices has not finished bringing up the client RPC server. RetriableException tells the calling framework (RetryProxy) that the failure is transient and the same call should be re-issued later, not surfaced to the user.

Source

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

   * @return {@link FSNamesystem} object.
   */
  public FSNamesystem getNamesystem() {
    return namesystem;
  }

  public NamenodeProtocols getRpcServer() {
    return rpcServer;
  }

  @VisibleForTesting
  public HttpServer2 getHttpServer() {
    return httpServer.getHttpServer();
  }

  public void queueExternalCall(ExternalCall<?> extCall)
      throws IOException, InterruptedException {
    if (rpcServer == null) {
      throw new RetriableException("Namenode is in startup mode");
    }
    rpcServer.getClientRpcServer().queueCall(extCall);
  }

  public static void initMetrics(Configuration conf, NamenodeRole role) {
    metrics = NameNodeMetrics.create(conf, role);
  }

  public static NameNodeMetrics getNameNodeMetrics() {
    return metrics;
  }

  /**
   * Try to obtain the actual client info according to the current user.
   * @param ipProxyUsers Users who can override client infos
   */
  private static String clientInfoFromContext(
      final String[] ipProxyUsers) {

View on GitHub (pinned to 2add963021)

Solutions

1. Retry the call: RetriableException is by design retryable; the client retry policy (ipc.Client / RetryProxy) will re-issue it once the NN is up.
2. Gate traffic on readiness: poll 'hdfs haadmin -getServiceStatus' or the JMX/RPC state until the NN reports active/standby-ready before issuing calls.
3. In HA clusters, ensure requests route through the configured failover proxy so they land on a ready NN.

// readiness gate before queueing external calls
HAServiceProtocol proto = haServiceProtocolProxy;
HAServiceStatus st = proto.getServiceStatus(); // throws until RPC server is up
if (st.getState() != HAServiceState.ACTIVE) throw new IllegalStateException("NN not active yet");

boolean isStartupRetryable(Throwable t) {
  return t instanceof org.apache.hadoop.ipc.RetriableException;
}

catch (RetriableException e) {
  // NN still in startup mode: honor the retry policy with backoff, do not surface to caller
  retryWithBackoff(extCall, /*initial*/1_000L, /*max*/30_000L, TimeUnit.MILLISECONDS);
}

When it happens

Trigger: Queueing an external call (RequestHedgingBroker/router-style external call path) in the window between NameNode construction and RPC server start, or against a standby NameNode where the client RPC server is not started.

Common situations: Clients firing requests immediately after the NN process starts; HA failover racing a NameNode restart; scripts that start the NN and instantly run jobs or admin commands against it.

Related errors

• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with
• Unsupported protocol found when creating the proxy connectio
• Datanode {datanode} not found.

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