{"record":{"id":"35cb4f1fa388ee6b","repo":"apache/seatunnel","slug":"please-set-kerberosprincipal","errorCode":null,"errorMessage":"Please set kerberosPrincipal","messagePattern":"Please set kerberosPrincipal","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/hadoop/HadoopFileSystemProxy.java","lineNumber":460,"sourceCode":"\n        IOException enhanced = new IOException(reason.toString());\n        if (cause != null) {\n            enhanced.addSuppressed(cause);\n        }\n        return enhanced;\n    }\n\n    private boolean enableKerberos() {\n        boolean kerberosPrincipalEmpty = StringUtils.isBlank(hadoopConf.getKerberosPrincipal());\n        boolean kerberosKeytabPathEmpty = StringUtils.isBlank(hadoopConf.getKerberosKeytabPath());\n        if (kerberosKeytabPathEmpty && kerberosPrincipalEmpty) {\n            return false;\n        }\n        if (!kerberosPrincipalEmpty && !kerberosKeytabPathEmpty) {\n            return true;\n        }\n        if (kerberosPrincipalEmpty) {\n            throw new IllegalArgumentException(\"Please set kerberosPrincipal\");\n        }\n        throw new IllegalArgumentException(\"Please set kerberosKeytabPath\");\n    }\n\n    private void initializeWithKerberosLogin() throws IOException, InterruptedException {\n        Pair<UserGroupInformation, FileSystem> pair =\n                HadoopLoginFactory.loginWithKerberos(\n                        configuration,\n                        hadoopConf.getKrb5Path(),\n                        hadoopConf.getKerberosPrincipal(),\n                        hadoopConf.getKerberosKeytabPath(),\n                        (configuration, userGroupInformation) -> {\n                            this.userGroupInformation = userGroupInformation;\n                            this.fileSystem = FileSystem.get(configuration);\n                            return Pair.of(userGroupInformation, fileSystem);\n                        });\n        userGroupInformation = pair.getKey();\n        fileSystem = pair.getValue();","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/hadoop/HadoopFileSystemProxy.java#L442-L478","documentation":"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\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add kerberos_principal = \"user@REALM\" to the file connector config","Double-check the option name spelling and that the value is not empty or whitespace","Verify the principal matches an entry in the provided keytab (kvno / klist -k)"],"exampleFix":"// before\nHdfsFile {\n  enable_kerberos = true\n  kerberos_keytab_path = \"/etc/security/keytab/hdfs.keytab\"\n}\n// after\nHdfsFile {\n  enable_kerberos = true\n  kerberos_principal = \"hdfs@EXAMPLE.COM\"\n  kerberos_keytab_path = \"/etc/security/keytab/hdfs.keytab\"\n}","handlingStrategy":"validation","validationCode":"if (Boolean.parseBoolean(config.get(\"enable_kerberos\")) && (config.get(\"kerberos_principal\") == null || config.get(\"kerberos_principal\").trim().isEmpty())) {\n    throw new IllegalArgumentException(\"enable_kerberos=true requires kerberos_principal\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    initHadoopFileSystem();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"kerberosPrincipal\")) {\n        // fix config: add kerberos_principal\n    } else {\n        throw e;\n    }\n}","preventionTips":["Always set kerberos_principal and kerberos_keytab_path together when enable_kerberos = true","Validate connector configs with a preflight script before submitting jobs"],"tags":["kerberos","config","hadoop"],"backgroundTag":"missing-required-config-field","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}