apache/dolphinscheduler · error · RuntimeException

Update Kerberos environment failed.

Error message

Update Kerberos environment failed.

What it means

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.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-hive/src/main/java/org/apache/dolphinscheduler/plugin/datasource/hive/HivePooledDataSourceClient.java:68

        checkKerberosEnv();
        UserGroupInformationFactory.login(baseConnectionParam.getUser());
        return super.createDataSourcePool(baseConnectionParam, dbType);
    }

    // used in constructor
    private void checkKerberosEnv() {
        String krb5File = PropertyUtils.getString(JAVA_SECURITY_KRB5_CONF_PATH);
        Boolean kerberosStartupState = PropertyUtils.getBoolean(HADOOP_SECURITY_AUTHENTICATION_STARTUP_STATE, false);
        if (kerberosStartupState && StringUtils.isNotBlank(krb5File)) {
            System.setProperty(JAVA_SECURITY_KRB5_CONF, krb5File);
            try {
                Config.refresh();
                Class<?> kerberosName = Class.forName("org.apache.hadoop.security.authentication.util.KerberosName");
                Field field = kerberosName.getDeclaredField("defaultRealm");
                field.setAccessible(true);
                field.set(null, Config.getInstance().getDefaultRealm());
            } catch (Exception e) {
                throw new RuntimeException("Update Kerberos environment failed.", e);
            }
        }
    }

    @Override
    public Connection getConnection() throws SQLException {
        try {
            return dataSource.getConnection();
        } catch (SQLException e) {
            synchronized (HikariDataSource.class) {
                UserGroupInformationFactory.logout(baseConnectionParam.getUser());
                UserGroupInformationFactory.login(baseConnectionParam.getUser());
                return dataSource.getConnection();
            }
        }
    }

    @Override

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Read the wrapped cause ('caused by') to see whether it was ClassNotFoundException, config parse failure, or reflection failure
2. Verify kerberos.yml exists on the classpath and contains all required fields with valid, readable file paths
3. Ensure the Hadoop-common/auth jars providing KerberosName are on the classpath and version-compatible
4. Fix java.security.auth.login.config / KRB5 paths (java.security.krb5.conf) if the underlying cause is JAAS/Krb5 config

Example fix

// before: hadoop-common absent or too old in datasource lib dir
// after: add matching hadoop-common jar
ls dolphinscheduler-datasource-plugin/hive/lib | grep hadoop-common
# copy hadoop-common-<same version as cluster> into the hive datasource lib directory

boolean kerberosReady = new File(kerberosYmlPath).exists()
    && Config.getInstance().getDefaultRealm() != null
    && new File(keytabPath).canRead();

boolean hasKerberosClass() {
  try { Class.forName("org.apache.hadoop.security.authentication.util.KerberosName"); return true; }
  catch (ClassNotFoundException e) { return false; }
}

try {
  client = new HivePooledDataSourceClient(connectionParam);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Update Kerberos environment failed")) {
    log.error("Kerberos env setup failed; check kerberos.yml and hadoop jars", e.getCause());
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• createUserGroupInformation fail.
• Parameter types: " + Lists.newArrayList(standardRpcRequest.g
• Close HadoopUtils instance failed
• DMS task init error
• get mainJarName failed:

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/54d4b061a788dbc0. Report an issue: GitHub.