{"record":{"id":"3197aca9553576b9","repo":"apache/hadoop","slug":"unable-to-load-oauth2-connection-factory","errorCode":null,"errorMessage":"Unable to load OAuth2 connection factory.","messagePattern":"Unable to load OAuth2 connection factory\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/URLConnectionFactory.java","lineNumber":140,"sourceCode":"\n    return conn;\n  }\n\n  /**\n   * Construct a new URLConnectionFactory that supports OAut-based connections.\n   * It will also try to load the SSL configuration when they are specified.\n   */\n  public static URLConnectionFactory newOAuth2URLConnectionFactory(\n      int connectTimeout, int readTimeout, Configuration conf)\n      throws IOException {\n    ConnectionConfigurator conn;\n    try {\n      ConnectionConfigurator sslConnConfigurator\n          = new SSLConnectionConfigurator(connectTimeout, readTimeout, conf);\n\n      conn = new OAuth2ConnectionConfigurator(conf, sslConnConfigurator);\n    } catch (Exception e) {\n      throw new IOException(\"Unable to load OAuth2 connection factory.\", e);\n    }\n    return new URLConnectionFactory(conn);\n  }\n\n  @VisibleForTesting\n  URLConnectionFactory(ConnectionConfigurator connConfigurator) {\n    this.connConfigurator = connConfigurator;\n  }\n\n  /**\n   * Opens a url with read and connect timeouts\n   *\n   * @param url\n   *          to open\n   * @return URLConnection\n   * @throws IOException\n   */\n  public URLConnection openConnection(URL url) throws IOException {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/URLConnectionFactory.java#L122-L158","documentation":"URLConnectionFactory.newOAuth2URLConnectionFactory builds an SSL configurator and an OAuth2ConnectionConfigurator for WebHDFS. Any exception while creating those objects, such as a missing required OAuth2 configuration value, an invalid access-token-provider class, or an SSL configuration failure, is wrapped in this IOException. It occurs during FileSystem initialization, before a WebHDFS request is made.","triggerScenarios":"Set dfs.webhdfs.oauth2.enabled=true without supplying all values required by the selected dfs.webhdfs.oauth2.access.token.provider. The default credential provider requires dfs.webhdfs.oauth2.credential, dfs.webhdfs.oauth2.client.id, and dfs.webhdfs.oauth2.refresh.url; the refresh-token provider also requires dfs.webhdfs.oauth2.refresh.token and its expiry. SSL setup or provider class instantiation failures are wrapped the same way.","commonSituations":"OAuth2 is enabled only in the client config while the token properties were not copied into core-site.xml or the job Configuration; a custom AccessTokenProvider class is missing or throws in setConf; ssl-client.xml or truststore settings are invalid; a deployment upgrades Hadoop and configuration key names are missed.","solutions":["Inspect the cause chain of the IOException to identify the exact missing key or class; the original IllegalArgumentException names the property.","For the default ConfCredentialBasedAccessTokenProvider, set dfs.webhdfs.oauth2.credential, dfs.webhdfs.oauth2.client.id, and dfs.webhdfs.oauth2.refresh.url.","For ConfRefreshTokenBasedAccessTokenProvider, also set dfs.webhdfs.oauth2.refresh.token and dfs.webhdfs.oauth2.refresh.token.expires.ms.since.epoch.","Verify dfs.webhdfs.oauth2.access.token.provider names a loadable AccessTokenProvider class and validate SSL/client certificate configuration when HTTPS is used."],"exampleFix":"// before\nconf.setBoolean(\"dfs.webhdfs.oauth2.enabled\", true);\nFileSystem fs = FileSystem.get(new URI(\"webhdfs://nn:9870\"), conf);\n\n// after\nconf.setBoolean(\"dfs.webhdfs.oauth2.enabled\", true);\nconf.set(\"dfs.webhdfs.oauth2.credential\", credentialRef);\nconf.set(\"dfs.webhdfs.oauth2.client.id\", clientId);\nconf.set(\"dfs.webhdfs.oauth2.refresh.url\", tokenEndpointUrl);\nFileSystem fs = FileSystem.get(new URI(\"webhdfs://nn:9870\"), conf);","handlingStrategy":"validation","validationCode":"if (conf.getBoolean(\"dfs.webhdfs.oauth2.enabled\", false)) {\n  String provider = conf.get(\"dfs.webhdfs.oauth2.access.token.provider\",\n      \"org.apache.hadoop.hdfs.web.oauth2.ConfCredentialBasedAccessTokenProvider\");\n  requireConf(conf, \"dfs.webhdfs.oauth2.client.id\");\n  requireConf(conf, \"dfs.webhdfs.oauth2.refresh.url\");\n  if (provider.endsWith(\"ConfCredentialBasedAccessTokenProvider\")) {\n    requireConf(conf, \"dfs.webhdfs.oauth2.credential\");\n  } else if (provider.endsWith(\"ConfRefreshTokenBasedAccessTokenProvider\")) {\n    requireConf(conf, \"dfs.webhdfs.oauth2.refresh.token\");\n    requireConf(conf, \"dfs.webhdfs.oauth2.refresh.token.expires.ms.since.epoch\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return URLConnectionFactory.newOAuth2URLConnectionFactory(connectTimeout, readTimeout, conf);\n} catch (IOException e) {\n  throw new IllegalArgumentException(\"Invalid WebHDFS OAuth2 configuration; inspect keys starting with dfs.webhdfs.oauth2.\", e);\n}","preventionTips":["Validate all dfs.webhdfs.oauth2.* keys before constructing the FileSystem.","Never enable OAuth2 with an empty or partially copied provider configuration.","Run a small GETFILESTATUS smoke test during deployment to catch initialization-time configuration errors."],"tags":["java","hadoop","webhdfs","oauth2","configuration","initialization"],"backgroundTag":"oauth2-misconfiguration","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}