apache/seatunnel · error · JdbcConnectorException

KERBEROS_AUTHENTICATION_FAILED

KERBEROS_AUTHENTICATION_FAILED

Error message

Kerberos authentication failed using this principal [%s] and keytab path [%s]

What it means

Hive JDBC sources support Kerberos authentication using a principal and keytab. When UserGroupInformation.loginUserFromKeytab (or equivalent) throws an IOException, this error wraps it, reporting which principal and keytab path failed. It signals the Kerberos login itself failed — bad credentials, unreadable keytab, or no Kerberos configuration on the JVM.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/utils/HiveJdbcUtils.java:65

                    principal,
                    keytabPath);
        } else {
            configuration.set("hadoop.security.authentication", "kerberos");
            UserGroupInformation.setConfiguration(configuration);
            try {
                log.info(
                        "Start Kerberos authentication using principal {} and keytab {}",
                        principal,
                        keytabPath);
                UserGroupInformation.loginUserFromKeytab(principal, keytabPath);
                log.info("Kerberos authentication successful");
            } catch (IOException e) {
                String errorMsg =
                        String.format(
                                "Kerberos authentication failed using this "
                                        + "principal [%s] and keytab path [%s]",
                                principal, keytabPath);
                throw new JdbcConnectorException(KERBEROS_AUTHENTICATION_FAILED, errorMsg, e);
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the keytab file exists and is readable by the process user on every node (klist -kt /path/to/keytab)
2. Confirm the principal exactly matches an entry in the keytab (kinit -kt keytab principal) and the realm matches krb5.conf
3. Set JVM Kerberos config (java.security.krb5.conf, useKeyTabTicket) and ensure HADOOP security configs are on the classpath
4. Check KDC reachability and clock sync (NTP); regenerate the keytab if credentials were rotated

Example fix

// before
url = "jdbc:hive2://host:10000/db";
// Kerberos flags omitted -> fails or misconfigures
// after
JdbcConnectionConfig cfg = JdbcConnectionConfig.builder()
    .setUrl("jdbc:hive2://host:10000/db;principal=hive/_HOST@REALM")
    .setKerberosPrincipal("user@EXAMPLE.COM")
    .setKerberosKeytabPath("/etc/security/keytabs/user.keytab")
    .build(); // ensure keytab is readable and principal matches `klist -kt`

import java.io.File;
if (keytabPath == null || !new File(keytabPath).canRead()) throw new IllegalStateException("Keytab unreadable: " + keytabPath);
// principal should match a `klist -kt keytab` entry exactly
Process kinit = new ProcessBuilder("kinit", "-kt", keytabPath, principal).inheritIO();
if (kinit.start().waitFor() != 0) throw new IllegalStateException("kinit failed for " + principal);

try {
  hiveUtils.doKerberosAuthentication(principal, keytabPath);
} catch (JdbcConnectorException e) {
  if ("KERBEROS_AUTHENTICATION_FAILED".equals(String.valueOf(e.getCode()))) {
    log.error("Check principal/keytab: {}", e.getMessage());
    // validate keytab with klist -kt, retry once after checking KDC
  }
}

When it happens

Trigger: doKerberosAuthentication is invoked when Kerberos is enabled for a Hive/other Kerberized JDBC connection and loginUserFromKeytab throws IOException: keytab file missing/unreadable, principal not present in keytab, clock skew, or missing krb5.conf/JAAS setup.

Common situations: Wrong principal spelling (must match keytab entry exactly, realm included); keytab path not accessible from all cluster nodes; KDC unreachable; HADOOP/Kerberos configs not distributed to worker nodes; expired keytab after password rotation.

Understand the failure class

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

Related errors

• Kerberos re-login for HiveMetaStore failed: {}
• Kerberos authentication is not configured, it will skip kerb
• Principal [{}] or keytabPath [{}] is empty, it will skip ker
• KERBEROS_AUTHORIZED_FAILED
• CommonErrorCode.KERBEROS_AUTHORIZED_FAILED

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