{"record":{"id":"bd4be2f26c8ffd12","repo":"apache/hadoop","slug":"state-store-driver-drivername-in-hostname-is-n","errorCode":null,"errorMessage":"State Store driver {driverName} in {hostname} is not ready.","messagePattern":"State Store driver (.+?) in (.+?) is not ready\\.","errorType":"exception","errorClass":"StateStoreUnavailableException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/store/driver/StateStoreDriver.java","lineNumber":186,"sourceCode":"\n  /**\n   * Check if the driver is currently running and the data store connection is\n   * valid.\n   *\n   * @return True if the driver is initialized and the data store is ready.\n   */\n  public abstract boolean isDriverReady();\n\n  /**\n   * Check if the driver is ready to be used and throw an exception otherwise.\n   *\n   * @throws StateStoreUnavailableException If the driver is not ready.\n   */\n  public void verifyDriverReady() throws StateStoreUnavailableException {\n    if (!isDriverReady()) {\n      String driverName = getDriverName();\n      String hostname = getHostname();\n      throw new StateStoreUnavailableException(\"State Store driver \" +\n          driverName + \" in \" + hostname + \" is not ready.\");\n    }\n  }\n\n  /**\n   * Close the State Store driver connection.\n   *\n   * @throws Exception if something goes wrong while closing the state store driver connection.\n   */\n  public void close() throws Exception {\n    if (executor != null) {\n      executor.shutdown();\n      executor = null;\n    }\n  }\n\n  /**\n   * Returns the current time synchronization from the underlying store.","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/store/driver/StateStoreDriver.java#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restore the state store backend named in the message (ZK quorum, MySQL, or the file-system state directory).","Verify the state store driver configuration (implementation class, connection string, path) in the router's hdfs-site.xml.","Check router logs for the driver initialization error that left it not-ready, fix it, and restart the router.","Watch State Store driver metrics (read/write failures, driver ready gauge) to confirm recovery."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Guard record operations with the driver's own check semantics\nif (!stateStoreDriver.isDriverReady()) {\n  // defer the operation; driver recovers when the backend does\n}","typeGuard":"boolean isStateStoreUnavailable(Throwable t) {\n  return t instanceof StateStoreUnavailableException\n      || (t != null && t.getMessage() != null\n          && t.getMessage().contains(\"is not ready\"));\n}","tryCatchPattern":"try {\n  return recordStore.putAll(records);\n} catch (StateStoreUnavailableException e) {\n  // driver/backend (ZK/MySQL/file) outage: retry with backoff;\n  // give up and page after the state store monitor window\n  retryWithBackoff(e);\n}","preventionTips":["Deploy the state store backend (ZK/MySQL) as HA and verify connectivity before router traffic.","Monitor the router's State Store driver metrics for read/write failures as a leading indicator.","In state-store clients, distinguish StateStoreUnavailableException from record IOExceptions: the former is retried, the latter surfaced."],"tags":["hdfs","router-based-federation","state-store","driver","availability"],"backgroundTag":"state-store-unavailable","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}