apache/seatunnel · error · CheckpointStorageException

Failed to login user from keytab : ${kerberosKeytabFilePath}

Error message

Failed to login user from keytab : ${kerberosKeytabFilePath} and kerberos principal : ${kerberosPrincipal}

What it means

HdfsConfiguration.authenticateKerberos performs UserGroupInformation.loginUserFromKeytab for secured HDFS clusters and wraps any IOException in CheckpointStorageException, reporting the keytab path and principal. It means Kerberos authentication with the supplied credentials failed before any HDFS operation started.

Source

Thrown at seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-hdfs/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/hdfs/common/HdfsConfiguration.java:113

        return hadoopConf;
    }

    /**
     * Authenticate kerberos
     *
     * @param kerberosPrincipal kerberos principal
     * @param kerberosKeytabFilePath kerberos keytab file path
     * @param hdfsConf hdfs configuration
     * @throws CheckpointStorageException authentication exception
     */
    private void authenticateKerberos(
            String kerberosPrincipal, String kerberosKeytabFilePath, Configuration hdfsConf)
            throws CheckpointStorageException {
        UserGroupInformation.setConfiguration(hdfsConf);
        try {
            UserGroupInformation.loginUserFromKeytab(kerberosPrincipal, kerberosKeytabFilePath);
        } catch (IOException e) {
            throw new CheckpointStorageException(
                    "Failed to login user from keytab : "
                            + kerberosKeytabFilePath
                            + " and kerberos principal : "
                            + kerberosPrincipal,
                    e);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Verify the keytab file exists and is readable by the SeaTunnel process user, and that the principal is listed in it (klist -kt).
Test credentials manually: kinit -kt <keytab> <principal>; fix realm/KDC issues in krb5.conf if that fails.
Check hadoop.security.authentication=kerberos and related properties in the supplied Configuration.
Check KDC reachability and host clock sync (clock skew causes login failures).

Example fix

// before
config.put("kerberosPrincipal", "wrong@EXAMPLE.COM");
config.put("kerberosKeytabFilePath", "/old/path/user.keytab");
// after
config.put("kerberosPrincipal", "correct@EXAMPLE.COM");
config.put("kerberosKeytabFilePath", "/etc/security/keytabs/correct.keytab");

Defensive patterns

Strategy: validation

Validate before calling

java.io.File keytab = new java.io.File(kerberosKeytabFilePath);
if (!keytab.canRead()) throw new IllegalStateException("Keytab unreadable: " + keytab);
// Optionally: klist -kt to confirm the principal exists in the keytab

Type guard

boolean kerberosReady(String principal, String keytabPath) {
    java.io.File f = new java.io.File(keytabPath);
    return f.exists() && f.canRead();
}

Try / catch

try {
    storage = new HdfsStorage(config);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("Failed to login user from keytab")) {
        throw new IllegalStateException("Kerberos login failed: check keytab path, principal, krb5.conf and KDC reachability", e);
    }
    throw e;
}

Prevention

Run kinit -kt <keytab> <principal> as the engine user before startup to verify credentials.
Keep krb5.conf and keytab paths in a managed, mounted location readable by the process.
Monitor KDC health and host clock sync (NTP) to avoid login failures.

When it happens

Trigger: buildConfiguration with kerberosPrincipal/kerberosKeytabFilePath set when the keytab file does not exist or is unreadable, the principal is not present in the keytab, the realm/KDC is unreachable, or hdfsConf lacks the required Kerberos settings (hadoop.security.authentication=kerberos, etc.).

Common situations: Wrong keytab path in the checkpoint storage config; keytab rotated and old principal removed; clock skew against the KDC; missing krb5.conf; principal name mismatch (host/realm casing).

Related errors

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