apache/seatunnel · error · IllegalArgumentException

Please set kerberosPrincipal

Error message

Please set kerberosPrincipal

What it means

IllegalArgumentException thrown by HiveMetaStoreProxyUtils.enableKerberos when kerberos authentication is requested but the kerberosPrincipal config is missing/empty. It fails fast at startup instead of failing later during metastore login.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreProxyUtils.java:40

import lombok.experimental.UtilityClass;

@UtilityClass
public class HiveMetaStoreProxyUtils {

    public boolean enableKerberos(ReadonlyConfig config) {
        boolean kerberosPrincipalEmpty =
                config.getOptional(FileBaseSourceOptions.KERBEROS_PRINCIPAL).isPresent();
        boolean kerberosKeytabPathEmpty =
                config.getOptional(FileBaseSourceOptions.KERBEROS_KEYTAB_PATH).isPresent();
        if (kerberosKeytabPathEmpty && kerberosPrincipalEmpty) {
            return true;
        }
        if (!kerberosPrincipalEmpty && !kerberosKeytabPathEmpty) {
            return false;
        }
        if (kerberosPrincipalEmpty) {
            throw new IllegalArgumentException("Please set kerberosPrincipal");
        }
        throw new IllegalArgumentException("Please set kerberosKeytabPath");
    }

    public boolean enableRemoteUser(ReadonlyConfig config) {
        return config.getOptional(FileBaseSourceOptions.REMOTE_USER).isPresent();
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add auth.kerberos-principal to the connector config (e.g. "auth.kerberos-principal" = "user/_HOST@REALM")
2. Ensure the value is not empty (check for failed env/variable substitution)
3. If kerberos is not intended, remove both kerberos principal and keytab options
4. Validate config with ReadonlyConfig.getOptional before constructing the catalog

Example fix

// before
Hive {
  auth.kerberos-keytab-path = "/etc/security/keytabs/hive.keytab"
}
// after
Hive {
  auth.kerberos-principal = "hive/_HOST@EXAMPLE.COM"
  auth.kerberos-keytab-path = "/etc/security/keytabs/hive.keytab"
}

ReadonlyConfig cfg = ReadonlyConfig.fromMap(configMap);
boolean principalSet = cfg.getOptional(KERBEROS_PRINCIPAL_OPTION).map(s -> !s.trim().isEmpty()).orElse(false);

boolean kerberosPrincipalValid = principal != null && !principal.trim().isEmpty();

try { enableKerberos(config); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Invalid kerberos config: " + e.getMessage()); }

When it happens

Trigger: enableKerberos(config) is called with kerberosPrincipal absent while kerberosKeytabPath is set (or both absent but auth.kerberos is enabled).

Common situations: Configuring Hive connector for a secured cluster but forgetting auth.kerberos-principal; only copying the keytab path from a template; variable interpolation resolving to an empty string.

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

• Please set kerberosKeytabPath
• Please set kerberosPrincipal
• Please set kerberosKeytabPath
• hadoop.security.authentication must be kerberos
• CREATE_HIVE_TABLE_FAILED

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