{"record":{"id":"3ab5e161c6cd1990","repo":"apache/hadoop","slug":"could-not-load-failover-proxy-provider-class-wh","errorCode":null,"errorMessage":"Could not load failover proxy provider class {} which is configured for authority {}","messagePattern":"Could not load failover proxy provider class (.+?) which is configured for authority (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java","lineNumber":294,"sourceCode":"\n  /** Gets the configured Failover proxy provider's class */\n  @VisibleForTesting\n  public static <T> Class<FailoverProxyProvider<T>> getFailoverProxyProviderClass(\n      Configuration conf, URI nameNodeUri) throws IOException {\n    if (nameNodeUri == null) {\n      return null;\n    }\n    String host = nameNodeUri.getHost();\n    String configKey = HdfsClientConfigKeys.Failover.PROXY_PROVIDER_KEY_PREFIX\n        + \".\" + host;\n    try {\n      @SuppressWarnings(\"unchecked\")\n      Class<FailoverProxyProvider<T>> ret = (Class<FailoverProxyProvider<T>>)\n          conf.getClass(configKey, null, FailoverProxyProvider.class);\n      return ret;\n    } catch (RuntimeException e) {\n      if (e.getCause() instanceof ClassNotFoundException) {\n        throw new IOException(\"Could not load failover proxy provider class \"\n            + conf.get(configKey) + \" which is configured for authority \"\n            + nameNodeUri, e);\n      } else {\n        throw e;\n      }\n    }\n  }\n\n  /**\n   * Creates an explicitly HA-enabled proxy object.\n   *\n   * @param conf the configuration object\n   * @param nameNodeUri the URI pointing either to a specific NameNode or to a\n   *        logical nameservice.\n   * @param xface the IPC interface which should be created\n   * @param failoverProxyProvider Failover proxy provider\n   * @return an object containing both the proxy and the associated\n   *         delegation token service it corresponds to","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java#L276-L312","documentation":"getFailoverProxyProviderClass reads dfs.ha.failover-proxy-provider.<host> (actually configKey = prefix + '.' + host) and loads the class via Configuration.getClass; when the underlying lookup fails with ClassNotFoundException (class name on record but not loadable), this IOException reports the configured class name and the authority. Built-in providers live in hadoop-hdfs-client, so in practice the value is a typo or the class sits in a jar missing from the client classpath.","triggerScenarios":"dfs.ha.failover-proxy-providers.<nameservice> is set to a misspelled or non-existent class; a custom provider class whose jar is absent on the node running the client; shaded/relocated deployments where the configured FQCN no longer matches relocated classes.","commonSituations":"Hand-edited hdfs-site.xml with wrong provider class name; custom failover logic deployed on some nodes but not the one raising the error; Maven shading that renames org.apache.hadoop classes without updating the config keys' values.","solutions":["Correct the class value — default should be org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider","If a custom provider is intended, add its jar to the client classpath and verify the FQCN with javap/Class.forName","Remove the dfs.ha.failover-proxy-provider key entirely to use the built-in default provider"],"exampleFix":"<!-- before -->\n<property>\n  <name>dfs.ha.failover-proxy-providers.myNameservice</name>\n  <value>org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProviders</value>\n</property> <!-- typo: Providers -->\n\n<!-- after -->\n<property>\n  <name>dfs.ha.failover-proxy-providers.myNameservice</name>\n  <value>org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider</value>\n</property>","handlingStrategy":"validation","validationCode":"String cls = conf.get(\"dfs.ha.failover-proxy-providers.\" + nameservice);\nif (cls != null) {\n  try {\n    Class.forName(cls); // loadable on this node?\n  } catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Provider class \" + cls + \" not on classpath\", e);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  provider = NameNodeProxiesClient.getFailoverProxyProviderClass(conf, u, xface);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Could not load failover proxy provider class\")) {\n    // fall back to the default provider when the custom one is optional\n    conf.unset(\"dfs.ha.failover-proxy-providers.\" + u.getHost());\n    provider = NameNodeProxiesClient.getFailoverProxyProviderClass(conf, u, xface);\n  } else throw e;\n}","preventionTips":["Spell the provider FQCN exactly; prefer omitting the key to use the built-in default","Deploy custom provider jars to every client node and verify with Class.forName in deploy checks","After shading/relocation, update all class-name config values to match new package names"],"tags":["hdfs","high-availability","class-not-found","configuration","classpath"],"backgroundTag":"class-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}