apache/hadoop · error · HadoopIllegalArgumentException

Unrecognized value '{}' for dfs.http.policy

Error message

Unrecognized value '{}' for dfs.http.policy

What it means

DFSUtil.getHttpPolicy reads dfs.http.policy (default HTTP_ONLY) and parses it with HttpConfig.Policy.fromString, which only accepts the enum names HTTP_ONLY, HTTPS_ONLY and HTTP_AND_HTTPS (case-insensitive). Any other string parses to null and the method throws HadoopIllegalArgumentException.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/DFSUtil.java:1611

   * @return DFS_WEB_AUTHENTICATION_KERBEROS_KEYTAB_KEY if the key is not empty
   *         else return defaultKey
   */
  public static String getSpnegoKeytabKey(Configuration conf, String defaultKey) {
    String value = 
        conf.get(DFSConfigKeys.DFS_WEB_AUTHENTICATION_KERBEROS_KEYTAB_KEY);
    return (value == null || value.isEmpty()) ?
        defaultKey : DFSConfigKeys.DFS_WEB_AUTHENTICATION_KERBEROS_KEYTAB_KEY;
  }

  /**
   * Get http policy.
   */
  public static HttpConfig.Policy getHttpPolicy(Configuration conf) {
    String policyStr = conf.get(DFSConfigKeys.DFS_HTTP_POLICY_KEY,
        DFSConfigKeys.DFS_HTTP_POLICY_DEFAULT);
    HttpConfig.Policy policy = HttpConfig.Policy.fromString(policyStr);
    if (policy == null) {
      throw new HadoopIllegalArgumentException("Unrecognized value '"
          + policyStr + "' for " + DFSConfigKeys.DFS_HTTP_POLICY_KEY);
    }

    conf.set(DFSConfigKeys.DFS_HTTP_POLICY_KEY, policy.name());
    return policy;
  }

  public static HttpServer2.Builder loadSslConfToHttpServerBuilder(HttpServer2.Builder builder,
      Configuration sslConf) {
    return builder
        .needsClientAuth(
            sslConf.getBoolean(DFS_CLIENT_HTTPS_NEED_AUTH_KEY,
                DFS_CLIENT_HTTPS_NEED_AUTH_DEFAULT))
        .keyPassword(getPassword(sslConf, DFS_SERVER_HTTPS_KEYPASSWORD_KEY))
        .keyStore(sslConf.get("ssl.server.keystore.location"),
            getPassword(sslConf, DFS_SERVER_HTTPS_KEYSTORE_PASSWORD_KEY),
            sslConf.get("ssl.server.keystore.type", "jks"))
        .trustStore(sslConf.get("ssl.server.truststore.location"),

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.http.policy to a valid enum name, e.g. HTTPS_ONLY or HTTP_AND_HTTPS
2. Remove the property to fall back to the default HTTP_ONLY
3. Double-check spelling/whitespace and restart the service

Example fix

// before
<property><name>dfs.http.policy</name><value>https</value></property>
// after
<property><name>dfs.http.policy</name><value>HTTPS_ONLY</value></property>

import org.apache.hadoop.http.HttpConfig;

String policy = conf.get("dfs.http.policy", "HTTP_ONLY");
if (HttpConfig.Policy.fromString(policy) == null) {
  throw new IllegalArgumentException("dfs.http.policy must be one of "
      + "HTTP_ONLY, HTTPS_ONLY, HTTP_AND_HTTPS, got: '" + policy + "'");
}

static boolean isValidHttpPolicy(String s) {
  return HttpConfig.Policy.fromString(s) != null;
}

catch (HadoopIllegalArgumentException e) during service startup; the message echoes the bad value - correct dfs.http.policy and restart rather than catching at runtime.

When it happens

Trigger: dfs.http.policy set to anything outside {HTTP_ONLY, HTTPS_ONLY, HTTP_AND_HTTPS}, e.g. 'https', 'true', 'both', or a typo like 'HTTPS_ONLY '. Any component calling getHttpPolicy (NameNode/DataNode HTTP server setup) hits it at startup.

Common situations: Enabling HTTPS with an intuitive-but-invalid value such as 'https' or 'https_only'; copying examples from mismatched distro documentation; stray whitespace in the value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Can not create a Path from a null string
• Can not create a Path from an empty string
• Property %s not specified
• no SharedFileDescriptorFactory paths were configured.
• Failed to create ${basePath}[source=${source}, allow-append=

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/57fe8a67ec9321c4. Report an issue: GitHub.