apache/hadoop · error · StateStoreUnavailableException

State Store driver {driverName} in {hostname} is not ready.

Error message

State Store driver {driverName} in {hostname} is not ready.

What it means

StateStoreDriver.verifyDriverReady() is the guard called before State Store record operations: if isDriverReady() is false (driver not initialized, or its backend connection failed), it throws StateStoreUnavailableException naming the driver implementation and the router hostname. It distinguishes a driver-level outage from per-record errors and is how the Router reports that its metadata backend cannot serve requests.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/store/driver/StateStoreDriver.java:186

  /**
   * Check if the driver is currently running and the data store connection is
   * valid.
   *
   * @return True if the driver is initialized and the data store is ready.
   */
  public abstract boolean isDriverReady();

  /**
   * Check if the driver is ready to be used and throw an exception otherwise.
   *
   * @throws StateStoreUnavailableException If the driver is not ready.
   */
  public void verifyDriverReady() throws StateStoreUnavailableException {
    if (!isDriverReady()) {
      String driverName = getDriverName();
      String hostname = getHostname();
      throw new StateStoreUnavailableException("State Store driver " +
          driverName + " in " + hostname + " is not ready.");
    }
  }

  /**
   * Close the State Store driver connection.
   *
   * @throws Exception if something goes wrong while closing the state store driver connection.
   */
  public void close() throws Exception {
    if (executor != null) {
      executor.shutdown();
      executor = null;
    }
  }

  /**
   * Returns the current time synchronization from the underlying store.

View on GitHub (pinned to 2add963021)

Solutions

1. Restore the state store backend named in the message (ZK quorum, MySQL, or the file-system state directory).
2. Verify the state store driver configuration (implementation class, connection string, path) in the router's hdfs-site.xml.
3. Check router logs for the driver initialization error that left it not-ready, fix it, and restart the router.
4. Watch State Store driver metrics (read/write failures, driver ready gauge) to confirm recovery.

// Guard record operations with the driver's own check semantics
if (!stateStoreDriver.isDriverReady()) {
  // defer the operation; driver recovers when the backend does
}

boolean isStateStoreUnavailable(Throwable t) {
  return t instanceof StateStoreUnavailableException
      || (t != null && t.getMessage() != null
          && t.getMessage().contains("is not ready"));
}

try {
  return recordStore.putAll(records);
} catch (StateStoreUnavailableException e) {
  // driver/backend (ZK/MySQL/file) outage: retry with backoff;
  // give up and page after the state store monitor window
  retryWithBackoff(e);
}

When it happens

Trigger: Any State Store record read/write while the driver is uninitialized (router starting) or its backend errored: ZooKeeper session lost, MySQL connection failure, file-based state directory unreadable; driver initialization failed at boot and every subsequent operation trips this check.

Common situations: ZooKeeper or MySQL outage behind the Router; state store root path/permissions changed; router restarted before the backend was up; misconfigured state store driver class or connection settings.

Related errors

• Cannot serialize field {} into JSON
• Mount table state store is not available.
• Disabled Nameservice state store is not available.
• Mount table state store is not available.
• No namenodes to invoke {methodName} with params {params} fro

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