apache/seatunnel · error · IllegalArgumentException

hadoop.security.authentication must be kerberos

Error message

hadoop.security.authentication must be kerberos

What it means

HadoopLoginFactory.loginWithKerberos requires the Hadoop configuration to explicitly set hadoop.security.authentication=kerberos before attempting a Kerberos login. If the property is absent or set to anything else, this IllegalArgumentException is thrown.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/dialect/hive/HadoopLoginFactory.java:38

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.security.UserGroupInformation;

import java.io.IOException;
import java.security.PrivilegedExceptionAction;

// todo: Add seatunnel-auth-kerberos module and move this to hive connector
public class HadoopLoginFactory {

    /** Login with kerberos, and do the given action after login successfully. */
    public static <T> T loginWithKerberos(
            Configuration configuration,
            String krb5FilePath,
            String kerberosPrincipal,
            String kerberosKeytabPath,
            LoginFunction<T> action)
            throws IOException, InterruptedException {
        if (!configuration.get("hadoop.security.authentication").equals("kerberos")) {
            throw new IllegalArgumentException("hadoop.security.authentication must be kerberos");
        }
        // Use global lock to avoid multiple threads to execute setConfiguration at the same time
        synchronized (UserGroupInformation.class) {
            System.setProperty("java.security.krb5.conf", krb5FilePath);
            // init configuration
            UserGroupInformation.setConfiguration(configuration);
            UserGroupInformation userGroupInformation =
                    UserGroupInformation.loginUserFromKeytabAndReturnUGI(
                            kerberosPrincipal, kerberosKeytabPath);
            return userGroupInformation.doAs(
                    (PrivilegedExceptionAction<T>)
                            () -> action.run(configuration, userGroupInformation));
        }
    }

    /** Login with remote user, and do the given action after login successfully. */
    public static <T> T loginWithRemoteUser(
            Configuration configuration, String remoteUser, LoginFunction<T> action)

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Set configuration.set("hadoop.security.authentication", "kerberos") before invoking the login.
  2. Ensure core-site.xml on the classpath contains <name>hadoop.security.authentication</name><value>kerberos</value>.
  3. If Kerberos is not intended, use the non-Kerberos login path instead of loginWithKerberos.

Example fix

// before
Configuration conf = new Configuration();
HadoopLoginFactory.login(conf, krb5, principal, keytab, action);
// after
Configuration conf = new Configuration();
conf.set("hadoop.security.authentication", "kerberos");
HadoopLoginFactory.login(conf, krb5, principal, keytab, action);
Defensive patterns

Strategy: validation

Validate before calling

if (!"kerberos".equals(conf.get("hadoop.security.authentication"))) { conf.set("hadoop.security.authentication", "kerberos"); }

Type guard

boolean isKerberosEnabled(org.apache.hadoop.conf.Configuration c) { return "kerberos".equals(c.get("hadoop.security.authentication")); }

Try / catch

try { HadoopLoginFactory.login(...); } catch (IllegalArgumentException e) { if (e.getMessage().contains("hadoop.security.authentication")) { /* set the property and retry */ } else throw e; }

Prevention

When it happens

Trigger: Calling the Kerberos login helper with a Hadoop Configuration that lacks hadoop.security.authentication=kerberos, typically when setting up Hive JDBC Kerberos auth.

Common situations: Users supply core-site.xml that does not enable kerberos, or build the Configuration programmatically and forget the property while still passing a principal/keytab.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/d7f2165ef2cddd56. Report an issue: GitHub.