apache/seatunnel · error · IllegalArgumentException

Please set kerberosPrincipal

Error message

Please set kerberosPrincipal

What it means

When Kerberos authentication is enabled for the file connector, enableKerberos validates that both kerberos_principal and kerberos_keytab_path are provided. If the principal is empty/absent while Kerberos is requested, it throws IllegalArgumentException("Please set kerberosPrincipal").

Source

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

        IOException enhanced = new IOException(reason.toString());
        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();

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Add kerberos_principal = "user@REALM" to the file connector config
  2. Double-check the option name spelling and that the value is not empty or whitespace
  3. Verify the principal matches an entry in the provided keytab (kvno / klist -k)

Example fix

// before
HdfsFile {
  enable_kerberos = true
  kerberos_keytab_path = "/etc/security/keytab/hdfs.keytab"
}
// 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_principal") == null || config.get("kerberos_principal").trim().isEmpty())) {
    throw new IllegalArgumentException("enable_kerberos=true requires kerberos_principal");
}

Try / catch

try {
    initHadoopFileSystem();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("kerberosPrincipal")) {
        // fix config: add kerberos_principal
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Setting enable_kerberos = true (or having non-empty keytab implying Kerberos) in an HDFS/S3/OSS file connector config without providing kerberos_principal; doWithHadoopAuth or initialize calls enableKerberos during filesystem initialization.

Common situations: Copying a working Kerberos config but omitting the principal; using a keytab-only setup expecting the principal to be derived from the keytab; typos in the option name so the value reads as empty.

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