{"record":{"id":"54d4b061a788dbc0","repo":"apache/dolphinscheduler","slug":"update-kerberos-environment-failed","errorCode":null,"errorMessage":"Update Kerberos environment failed.","messagePattern":"Update Kerberos environment failed\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-hive/src/main/java/org/apache/dolphinscheduler/plugin/datasource/hive/HivePooledDataSourceClient.java","lineNumber":68,"sourceCode":"        checkKerberosEnv();\n        UserGroupInformationFactory.login(baseConnectionParam.getUser());\n        return super.createDataSourcePool(baseConnectionParam, dbType);\n    }\n\n    // used in constructor\n    private void checkKerberosEnv() {\n        String krb5File = PropertyUtils.getString(JAVA_SECURITY_KRB5_CONF_PATH);\n        Boolean kerberosStartupState = PropertyUtils.getBoolean(HADOOP_SECURITY_AUTHENTICATION_STARTUP_STATE, false);\n        if (kerberosStartupState && StringUtils.isNotBlank(krb5File)) {\n            System.setProperty(JAVA_SECURITY_KRB5_CONF, krb5File);\n            try {\n                Config.refresh();\n                Class<?> kerberosName = Class.forName(\"org.apache.hadoop.security.authentication.util.KerberosName\");\n                Field field = kerberosName.getDeclaredField(\"defaultRealm\");\n                field.setAccessible(true);\n                field.set(null, Config.getInstance().getDefaultRealm());\n            } catch (Exception e) {\n                throw new RuntimeException(\"Update Kerberos environment failed.\", e);\n            }\n        }\n    }\n\n    @Override\n    public Connection getConnection() throws SQLException {\n        try {\n            return dataSource.getConnection();\n        } catch (SQLException e) {\n            synchronized (HikariDataSource.class) {\n                UserGroupInformationFactory.logout(baseConnectionParam.getUser());\n                UserGroupInformationFactory.login(baseConnectionParam.getUser());\n                return dataSource.getConnection();\n            }\n        }\n    }\n\n    @Override","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-hive/src/main/java/org/apache/dolphinscheduler/plugin/datasource/hive/HivePooledDataSourceClient.java#L50-L86","documentation":"HivePooledDataSourceClient.checkKerberosEnv wraps any failure while refreshing Hadoop config and resetting KerberosName.defaultRealm in a RuntimeException. It means the Kerberos environment could not be prepared before creating the Hive connection pool — root causes range from missing/malformed kerberos.yml entries to missing Hadoop security classes.","triggerScenarios":"createDataSourcePool -> checkKerberosEnv when kerberos is enabled: Class.forName on org.apache.hadoop.security.authentication.util.KerberosName fails, Config.refresh() throws (bad/missing kerberos config), or the defaultRealm field access fails due to a Hadoop version change.","commonSituations":"kerberos.yml missing keys (defaultRealm, keytab, principal paths) or with wrong file paths; Hadoop-common version on classpath lacking KerberosName.defaultRealm (version mismatch); unreadable keytab file path.","solutions":["Read the wrapped cause ('caused by') to see whether it was ClassNotFoundException, config parse failure, or reflection failure","Verify kerberos.yml exists on the classpath and contains all required fields with valid, readable file paths","Ensure the Hadoop-common/auth jars providing KerberosName are on the classpath and version-compatible","Fix java.security.auth.login.config / KRB5 paths (java.security.krb5.conf) if the underlying cause is JAAS/Krb5 config"],"exampleFix":"// before: hadoop-common absent or too old in datasource lib dir\n// after: add matching hadoop-common jar\nls dolphinscheduler-datasource-plugin/hive/lib | grep hadoop-common\n# copy hadoop-common-<same version as cluster> into the hive datasource lib directory","handlingStrategy":"try-catch","validationCode":"boolean kerberosReady = new File(kerberosYmlPath).exists()\n    && Config.getInstance().getDefaultRealm() != null\n    && new File(keytabPath).canRead();","typeGuard":"boolean hasKerberosClass() {\n  try { Class.forName(\"org.apache.hadoop.security.authentication.util.KerberosName\"); return true; }\n  catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n  client = new HivePooledDataSourceClient(connectionParam);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Update Kerberos environment failed\")) {\n    log.error(\"Kerberos env setup failed; check kerberos.yml and hadoop jars\", e.getCause());\n  } else throw e;\n}","preventionTips":["Validate kerberos.yml fields and file paths before enabling Kerberos datasources","Pin hadoop-common version compatible with your cluster","Confirm keytab/krb5.conf readable on all worker hosts","Keep NTP synced"],"tags":["kerberos","hive","hadoop","reflection"],"backgroundTag":"kerberos-setup-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}