apache/hadoop · critical · ServletException

Authentication type must be specified: simple|kerberos|<clas

Error message

Authentication type must be specified: simple|kerberos|<class>

What it means

AuthenticationFilter.init reads its configuration (with the configured prefix), looks up the 'type' property, and refuses to start with ServletException if no authentication type is given — the message lists the expected values: simple (PseudoAuthenticationHandler.TYPE), kerberos (KerberosAuthenticationHandler.TYPE), or a custom AuthenticationHandler class name. A filter that fails init takes the whole web application down, so this surfaces as a deployment error at context startup, not at request time.

Source

Thrown at hadoop-common-project/hadoop-auth/src/main/java/org/apache/hadoop/security/authentication/server/AuthenticationFilter.java:164

  /**
   * <p>Initializes the authentication filter and signer secret provider.</p>
   * It instantiates and initializes the specified {@link
   * AuthenticationHandler}.
   *
   * @param filterConfig filter configuration.
   *
   * @throws ServletException thrown if the filter or the authentication handler could not be initialized properly.
   */
  @Override
  public void init(FilterConfig filterConfig) throws ServletException {
    String configPrefix = filterConfig.getInitParameter(CONFIG_PREFIX);
    configPrefix = (configPrefix != null) ? configPrefix + "." : "";
    config = getConfiguration(configPrefix, filterConfig);
    String authHandlerName = config.getProperty(AUTH_TYPE, null);
    String authHandlerClassName;
    if (authHandlerName == null) {
      throw new ServletException("Authentication type must be specified: " +
          PseudoAuthenticationHandler.TYPE + "|" + 
          KerberosAuthenticationHandler.TYPE + "|<class>");
    }
    authHandlerClassName =
        AuthenticationHandlerUtil
            .getAuthenticationHandlerClassName(authHandlerName);
    maxInactiveInterval = Long.parseLong(config.getProperty(
        AUTH_TOKEN_MAX_INACTIVE_INTERVAL, "-1")); // By default, disable.
    if (maxInactiveInterval > 0) {
      maxInactiveInterval *= 1000;
    }
    validity = Long.parseLong(config.getProperty(AUTH_TOKEN_VALIDITY, "36000"))
        * 1000; //10 hours
    initializeSecretProvider(filterConfig);

    initializeAuthHandler(authHandlerClassName, filterConfig);

    cookieDomain = config.getProperty(COOKIE_DOMAIN, null);

View on GitHub (pinned to 2add963021)

Solutions

1. Add the init-param to the filter in web.xml: param-name 'type', param-value 'kerberos', 'simple', or your handler FQCN — or set it in the external config the filter loads.
2. If config.prefix is set, verify every property carries that prefix (e.g. prefix.type) and matches exactly.
3. Check for typos/case in property names and ensure the XML is well-formed (no lost params during merge).
4. For custom handlers, confirm the class is on the classpath and implements AuthenticationHandler, otherwise the type resolves to nothing.
5. Redeploy and watch the startup log: init failures are logged before any request can succeed.

Example fix

<!-- web.xml — before: filter has no authentication type -->
<filter>
  <filter-name>auth</filter-name>
  <filter-class>org.apache.hadoop.security.authentication.server.AuthenticationFilter</filter-class>
</filter>

<!-- after -->
<filter>
  <filter-name>auth</filter-name>
  <filter-class>org.apache.hadoop.security.authentication.server.AuthenticationFilter</filter-class>
  <init-param>
    <param-name>type</param-name>
    <param-value>kerberos</param-value>
  </init-param>
</filter>

// deployment check before the filter ever initializes
Properties p = loadAuthConfig();
if (p.getProperty("type") == null && p.getProperty(prefix + ".type") == null) {
  throw new IllegalArgumentException("authentication.type missing: set type=simple|kerberos|<handler-class>");
}

When it happens

Trigger: Deploying the hadoop-auth AuthenticationFilter (directly or via WebHDFS/httpfs/Oozie/etc.) with web.xml or config missing the authentication.type property; setting a config-prefix (config.prefix init-param) so 'type' is expected as prefix.type while the property is stored unprefixed (or vice versa); typos in the property name.

Common situations: Copying a filter definition from docs but dropping the init-params; adding a prefix after the fact without renaming existing properties; XML property outside the right section; environment-specific web.xml overlays losing the param; upgrading a service whose new version reads the type under a new name.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• CertificateException - be sure not to include PEM header and
• CertificateException - PEM may be corrupt
• No secret in signature secret file: ${signatureSecretFile}
• Could not read signature secret file: ${signatureSecretFile}
• signer.secret.provider.zookeeper.path must be specified

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