apache/seatunnel · error · IllegalArgumentException

Please set kerberosKeytabPath

Error message

Please set kerberosKeytabPath

What it means

The counterpart of the kerberosPrincipal check: enableKerberos requires both a principal and a keytab. When the principal is set but kerberos_keytab_path is empty/absent, it throws IllegalArgumentException("Please set kerberosKeytabPath").

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/hadoop/HadoopFileSystemProxy.java:462

        if (cause != null) {
            enhanced.addSuppressed(cause);
        }
        return enhanced;
    }

    private boolean enableKerberos() {
        boolean kerberosPrincipalEmpty = StringUtils.isBlank(hadoopConf.getKerberosPrincipal());
        boolean kerberosKeytabPathEmpty = StringUtils.isBlank(hadoopConf.getKerberosKeytabPath());
        if (kerberosKeytabPathEmpty && kerberosPrincipalEmpty) {
            return false;
        }
        if (!kerberosPrincipalEmpty && !kerberosKeytabPathEmpty) {
            return true;
        }
        if (kerberosPrincipalEmpty) {
            throw new IllegalArgumentException("Please set kerberosPrincipal");
        }
        throw new IllegalArgumentException("Please set kerberosKeytabPath");
    }

    private void initializeWithKerberosLogin() throws IOException, InterruptedException {
        Pair<UserGroupInformation, FileSystem> pair =
                HadoopLoginFactory.loginWithKerberos(
                        configuration,
                        hadoopConf.getKrb5Path(),
                        hadoopConf.getKerberosPrincipal(),
                        hadoopConf.getKerberosKeytabPath(),
                        (configuration, userGroupInformation) -> {
                            this.userGroupInformation = userGroupInformation;
                            this.fileSystem = FileSystem.get(configuration);
                            return Pair.of(userGroupInformation, fileSystem);
                        });
        userGroupInformation = pair.getKey();
        fileSystem = pair.getValue();
        fileSystem.setWriteChecksum(false);
        log.info("Create FileSystem success with Kerberos: {}.", hadoopConf.getKerberosPrincipal());

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Add kerberos_keytab_path = "/path/to/user.keytab" to the connector config
  2. Ensure the keytab file exists and is readable by the SeaTunnel process at that path (mount it in containers)
  3. Confirm enable_kerberos = true is intentional and both kerberos options are present

Example fix

// before
HdfsFile {
  enable_kerberos = true
  kerberos_principal = "hdfs@EXAMPLE.COM"
}
// after
HdfsFile {
  enable_kerberos = true
  kerberos_principal = "hdfs@EXAMPLE.COM"
  kerberos_keytab_path = "/etc/security/keytab/hdfs.keytab"
}
Defensive patterns

Strategy: validation

Validate before calling

if (Boolean.parseBoolean(config.get("enable_kerberos")) && (config.get("kerberos_keytab_path") == null || config.get("kerberos_keytab_path").trim().isEmpty())) {
    throw new IllegalArgumentException("enable_kerberos=true requires kerberos_keytab_path");
}

Try / catch

try {
    initHadoopFileSystem();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("kerberosKeytabPath")) {
        // fix config: add kerberos_keytab_path and ensure file exists
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Setting kerberos_principal (with Kerberos enabled) but omitting kerberos_keytab_path in the file connector config; initialize/doWithHadoopAuth calls enableKerberos and reaches the final throw.

Common situations: Trying password-based Kerberos and assuming keytab is optional; forgetting to mount/copy the keytab path into containerized deployments so the config value was removed; partial config migrations.

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/7a329adff210fbb6. Report an issue: GitHub.