{"record":{"id":"90488c44df7ab16e","repo":"apache/hadoop","slug":"cached-state-store-not-initialized-recordclass","errorCode":null,"errorMessage":"Cached State Store not initialized, {recordClass} records not valid","messagePattern":"Cached State Store not initialized, (.+?) records not valid","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/CachedRecordStore.java","lineNumber":104,"sourceCode":"   * @param clazz Class of the record to store.\n   * @param driver State Store driver.\n   * @param over If the entries should be overridden if they expire\n   */\n  protected CachedRecordStore(\n      Class<R> clazz, StateStoreDriver driver, boolean over) {\n    super(clazz, driver);\n\n    this.override = over;\n  }\n\n  /**\n   * Check that the cache of the State Store information is available.\n   *\n   * @throws StateStoreUnavailableException If the cache is not initialized.\n   */\n  private void checkCacheAvailable() throws StateStoreUnavailableException {\n    if (!getDriver().isDriverReady() || !this.initialized) {\n      throw new StateStoreUnavailableException(\n          \"Cached State Store not initialized, \" +\n          getRecordClass().getSimpleName() + \" records not valid\");\n    }\n  }\n\n  @Override\n  public boolean loadCache(boolean force) throws IOException {\n    // Prevent loading the cache too frequently\n    if (force || isUpdateTime()) {\n      List<R> newRecords = null;\n      long t = -1;\n      long startTime = Time.monotonicNow();\n      try {\n        QueryResult<R> result = getDriver().get(getRecordClass());\n        newRecords = result.getRecords();\n        t = result.getTimestamp();\n\n        // If we have any expired record, update the State Store","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/store/CachedRecordStore.java#L86-L122","documentation":"CachedRecordStore backs the Router's cached views of State Store data (membership, mount table, etc.). checkCacheAvailable() runs before serving any cached records and throws StateStoreUnavailableException unless the underlying driver isDriverReady() AND this.initialized is true — meaning the cache was never loaded for this record type or the driver went away. The message names the record class whose records cannot be trusted.","triggerScenarios":"An RPC or mount-table resolution hits the cached store before the State Store service completed its first loadCache (router startup race); the state store driver transitioned to not-ready (ZK/MySQL/file backend down) while the cache is marked uninitialized; router still in startup/safemode state serving requests.","commonSituations":"Router just restarted and clients or a load balancer immediately send requests; state store backend outage; cache refresh failing repeatedly so the store never becomes initialized.","solutions":["Wait for Router initialization to complete and take the router out of safemode ('hdfs dfsrouteradmin -safemode leave') once the State Store is reachable.","Fix State Store backend connectivity (ZooKeeper/MySQL/state directory) — check the driver-specific errors in the log.","Confirm the State Store service is running via router JMX/state and that cache refreshes succeed.","Retry the request after recovery; the cache loads on the next refresh cycle and the exception stops."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Check cache/driver readiness before issuing router RPC-dependent work\nif (!stateStore.isDriverReady()\n    || !stateStore.getRecordStore(MembershipState.class).isInitialized()) {\n  // wait for the state store cache load instead of failing the request\n}","typeGuard":"boolean isStateStoreUnavailable(Throwable t) {\n  return t instanceof StateStoreUnavailableException\n      || (t instanceof IOException && t.getMessage() != null\n          && t.getMessage().contains(\"Cached State Store not initialized\"));\n}","tryCatchPattern":"try {\n  return routerRpcServer.getFileInfo(path);\n} catch (StateStoreUnavailableException e) {\n  // router cache not loaded yet (startup race or store outage):\n  // back off and retry — the cache loads on the next refresh cycle\n  Thread.sleep(1000L * attempt);\n}","preventionTips":["Take routers out of the load balancer until they report RUNNING with a loaded state store cache.","Leave safemode explicitly ('hdfs dfsrouteradmin -safemode leave') in automated cluster bring-up once the store is healthy.","Make State Store backend (ZK/DB) highly available; cache init failures almost always trace to backend outages."],"tags":["hdfs","router-based-federation","state-store","cache","startup-race"],"backgroundTag":"state-store-unavailable","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}