{"record":{"id":"e68877a71324a9cb","repo":"apache/hadoop","slug":"couldn-t-create-proxy-provider","errorCode":null,"errorMessage":"Couldn't create proxy provider {}","messagePattern":"Couldn't create proxy provider (.+?)","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":256,"sourceCode":"          .getConstructor(Configuration.class, URI.class,\n              Class.class, HAProxyFactory.class);\n      FailoverProxyProvider<T> provider = ctor.newInstance(conf, nameNodeUri,\n          xface, proxyFactory);\n\n      // If the proxy provider is of an old implementation, wrap it.\n      if (!(provider instanceof AbstractNNFailoverProxyProvider)) {\n        providerNN = new WrappedFailoverProxyProvider<>(provider);\n      } else {\n        providerNN = (AbstractNNFailoverProxyProvider<T>)provider;\n      }\n    } catch (Exception e) {\n      final String message = \"Couldn't create proxy provider \" +\n          failoverProxyProviderClass;\n      LOG.debug(message, e);\n      if (e.getCause() instanceof IOException) {\n        throw (IOException) e.getCause();\n      } else {\n        throw new IOException(message, e);\n      }\n    }\n\n    // Check the port in the URI, if it is logical.\n    if (checkPort && providerNN.useLogicalURI()) {\n      int port = nameNodeUri.getPort();\n      if (port > 0 &&\n          port != HdfsClientConfigKeys.DFS_NAMENODE_RPC_PORT_DEFAULT) {\n        // Throwing here without any cleanup is fine since we have not\n        // actually created the underlying proxies yet.\n        throw new IOException(\"Port \" + port + \" specified in URI \"\n            + nameNodeUri + \" but host '\" + nameNodeUri.getHost()\n            + \"' is a logical (HA) namenode\"\n            + \" and does not use port information.\");\n      }\n    }\n    providerNN.setFallbackToSimpleAuth(fallbackToSimpleAuth);\n    return providerNN;","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java#L238-L274","documentation":"While creating the HA failover proxy, NameNodeProxiesClient instantiates the configured FailoverProxyProvider class inside a try block; any exception from the provider's constructor (most often ConfiguredFailoverProxyProvider failing to resolve per-NameNode addresses) is caught here. If the cause is an IOException it is rethrown directly; otherwise it is wrapped with 'Couldn't create proxy provider <class>'. The root cause is almost always incomplete HA configuration for the nameservice.","triggerScenarios":"Creating a DFSClient against an HA nameservice (hdfs://myNameservice) where dfs.ha.namenodes.myNameservice is unset/misnamed, dfs.namenode.rpc-address.myNameservice.<nn> entries are missing, or the configured provider class's constructor throws (bad URI, unknown host) for any individual NameNode.","commonSituations":"Client side lacks the cluster's hdfs-site.xml HA block; typo in the nameservice (dfs.ha.namenodes.mynamservice); HA enabled on the cluster but client config only has fs.defaultFS pointing at the logical URI; custom failover provider classes whose constructor requirements changed between versions.","solutions":["Ship the cluster's hdfs-site.xml/core-site.xml to the client and verify dfs.ha.namenodes.<nameservice> plus every dfs.namenode.rpc-address.<nameservice>.<id> is present","Check the nested cause in the stack trace — it names the exact missing address/config","Confirm fs.defaultFS uses the same logical nameservice string as the dfs.ha.* keys (case/underscore exact)","If using a custom failover proxy provider, ensure its jar and constructor dependencies are on the client classpath"],"exampleFix":"<!-- before -->\n<property><name>fs.defaultFS</name><value>hdfs://myNameservice</value></property>\n<!-- no dfs.ha.namenodes.* entries -->\n\n<!-- after -->\n<property><name>fs.defaultFS</name><value>hdfs://myNameservice</value></property>\n<property><name>dfs.ha.namenodes.myNameservice</name><value>nn1,nn2</value></property>\n<property><name>dfs.namenode.rpc-address.myNameservice.nn1</name><value>nn1-host:8020</value></property>\n<property><name>dfs.namenode.rpc-address.myNameservice.nn2</name><value>nn2-host:8020</value></property>","handlingStrategy":"validation","validationCode":"// Validate HA config before creating clients:\nString ns = uri.getHost();\nString namenodes = conf.get(\"dfs.ha.namenodes.\" + ns);\nif (namenodes == null) throw new IllegalArgumentException(\"dfs.ha.namenodes.\" + ns + \" missing\");\nfor (String id : namenodes.split(\",\")) {\n  if (conf.get(\"dfs.namenode.rpc-address.\" + ns + \".\" + id) == null)\n    throw new IllegalArgumentException(\"dfs.namenode.rpc-address.\" + ns + \".\" + id + \" missing\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs = FileSystem.get(new URI(\"hdfs://myNameservice\"), conf);\n} catch (IOException e) {\n  // inspect e.getCause(): the nested IOException names the missing HA property\n  log.error(\"HA proxy creation failed: {}\", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());\n  throw e;\n}","preventionTips":["Distribute the cluster's full hdfs-site.xml to clients instead of hand-copying properties","Validate the HA key quartet (dfs.ha.namenodes, both rpc-addresses, failover provider) in config tests","Spell the nameservice identically everywhere — it is case-sensitive and appears in every key"],"tags":["hdfs","high-availability","namenode","configuration","ha"],"backgroundTag":"ha-misconfiguration","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}