What causes "Kerberos authentication failed: %s" in apache/seatunnel?

Read the embedded cause (%s) and fix the underlying Kerberos error — most often fix the keytab path, principal spelling, or krb5.conf path in the connector config

apache/seatunnel · error · IcebergConnectorException

CommonErrorCode.KERBEROS_AUTHORIZED_FAILED

CommonErrorCode.KERBEROS_AUTHORIZED_FAILED

Error message

Kerberos authentication failed: %s

What it means

IcebergCatalogLoader.doKerberosLogin wraps any exception from the Kerberos login sequence (setting krb5 conf/principal system properties and UserGroupInformation login from keytab) into an IcebergConnectorException with CommonErrorCode.KERBEROS_AUTHORIZED_FAILED. It signals that the connector could not authenticate to a Kerberized Hadoop/cluster environment while loading the catalog.

Source

Thrown at seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergCatalogLoader.java:145

    /**
     * kerberos authentication
     *
     * @param configuration Configuration
     */
    private Configuration doKerberosLogin(Configuration configuration) {
        String kerberosKrb5ConfPath = config.getKerberosKrb5ConfPath();
        String kerberosKeytabPath = config.getKerberosKeytabPath();
        String kerberosPrincipal = config.getKerberosPrincipal();

        if (StringUtils.isNotEmpty(kerberosPrincipal)
                && StringUtils.isNotEmpty(kerberosKrb5ConfPath)
                && StringUtils.isNotEmpty(kerberosKeytabPath)) {
            try {
                System.setProperty("java.security.krb5.conf", kerberosKrb5ConfPath);
                System.setProperty("krb.principal", kerberosPrincipal);
                doKerberosAuthentication(configuration, kerberosPrincipal, kerberosKeytabPath);
            } catch (Exception e) {
                throw new IcebergConnectorException(
                        CommonErrorCode.KERBEROS_AUTHORIZED_FAILED,
                        String.format("Kerberos authentication failed: %s", e.getMessage()));
            }
        } else {
            log.warn(
                    "Kerberos authentication is not configured, it will skip kerberos authentication");
        }

        return configuration;
    }

    public static void doKerberosAuthentication(
            Configuration configuration, String principal, String keytabPath) {
        if (StringUtils.isBlank(principal) || StringUtils.isBlank(keytabPath)) {
            log.warn(
                    "Principal [{}] or keytabPath [{}] is empty, it will skip kerberos authentication",
                    principal,
                    keytabPath);

View on GitHub (pinned to cf67b549a7)

Solutions

Read the embedded cause (%s) and fix the underlying Kerberos error — most often fix the keytab path, principal spelling, or krb5.conf path in the connector config
Verify the keytab exists and is readable on every worker node and contains the configured principal (klist -kt <keytab>)
Test authentication outside SeaTunnel with kinit -kt <keytab> <principal> to isolate KDC/realm/ENCTYPE issues
Ensure krb5.conf has correct realms/KDC entries and the hosts involved have correct forward/reverse DNS
Install unlimited-strength JCE policy files if you see 'no supported default etypes' style errors

Example fix

// before
Kerberos { principal = "user@WRONG.REALM", keytab_path = "/etc/keytabs/stale.keytab", krb5_conf_path = "/missing/krb5.conf" }
// after
Kerberos { principal = "user@EXAMPLE.COM", keytab_path = "/etc/security/keytabs/user.keytab", krb5_conf_path = "/etc/krb5.conf" }

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight check before submitting the job
Process p = new ProcessBuilder("kinit", "-kt", keytabPath, principal).start();
if (p.waitFor() != 0) throw new IllegalStateException("kinit failed; fix keytab/principal before running");
if (!new File(krb5ConfPath).canRead()) throw new IllegalStateException("krb5.conf missing: " + krb5ConfPath);

Try / catch

try {
  catalogLoader.loadCatalog();
} catch (IcebergConnectorException e) {
  if (CommonErrorCode.KERBEROS_AUTHORIZED_FAILED.equals(e.getCode())) {
    // surface e.getMessage() (contains root cause), fix keytab/krb5.conf, re-kinit
  } else throw e;
}

Prevention

Distribute keytab and krb5.conf to every worker node with correct permissions
Validate principal+keytab with kinit outside the connector first
Keep realms/KDC entries in krb5.conf correct and DNS consistent
Match JVM enctypes/JCE policy to the keytab's encryption types

When it happens

Trigger: loadHadoopConfig detects kerberosPrincipal and kerberosKeytabPath are configured, calls doKerberosAuthentication, and it throws (missing krb5.conf file, bad principal, unreadable/expired keytab, clock skew, wrong realm) — the original message is embedded via %s.

Common situations: Wrong path to krb5.conf or keytab file on worker nodes; principal not present in the KDC or keytab; keytab/ktutil generated for wrong principal or enctypes unsupported by the JVM (e.g. missing JCE); hostname/reverse-DNS mismatch causing 'Server not found in Kerberos database'.

Understand the failure class

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

Related errors

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