apache/dolphinscheduler · error · RuntimeException

createUserGroupInformation fail.

Error message

createUserGroupInformation fail. 

What it means

UserGroupInformationFactory.createKerberosUser wraps IOException from UserGroupInformation.loginUserFromKeytabAndReturnUGI in a RuntimeException. It means Kerberos login with the given principal and keytab failed — typically bad credentials, unreadable keytab, clock skew, or KDC/realm misconfiguration.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-hive/src/main/java/org/apache/dolphinscheduler/plugin/datasource/hive/security/UserGroupInformationFactory.java:116

        String krb5File = PropertyUtils.getString(Constants.JAVA_SECURITY_KRB5_CONF_PATH);
        String keytab = PropertyUtils.getString(Constants.LOGIN_USER_KEY_TAB_PATH);
        String principal = PropertyUtils.getString(Constants.LOGIN_USER_KEY_TAB_USERNAME);
        if (StringUtils.isNotBlank(krb5File)) {
            System.setProperty(Constants.JAVA_SECURITY_KRB5_CONF, krb5File);
        }

        Configuration hadoopConf = new Configuration();
        hadoopConf.setBoolean("ipc.client.fallback-to-simple-auth-allowed", true);
        hadoopConf.set(Constants.HADOOP_SECURITY_AUTHENTICATION, Constants.KERBEROS);

        try {
            UserGroupInformation.setConfiguration(hadoopConf);
            UserGroupInformation userGroupInformation =
                    UserGroupInformation.loginUserFromKeytabAndReturnUGI(principal.trim(), keytab.trim());
            UserGroupInformation.setLoginUser(userGroupInformation);
            return userGroupInformation;
        } catch (IOException e) {
            throw new RuntimeException("createUserGroupInformation fail. ", e);
        }
    }

    public static boolean openKerberos() {
        String resUploadStartupType = PropertyUtils.getUpperCaseString(Constants.RESOURCE_STORAGE_TYPE);
        StorageType storageType = StorageType.valueOf(resUploadStartupType);
        Boolean kerberosStartupState =
                PropertyUtils.getBoolean(Constants.HADOOP_SECURITY_AUTHENTICATION_STARTUP_STATE, false);
        return storageType == StorageType.HDFS && kerberosStartupState;
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect the wrapped IOException cause for the exact kinit-style failure (e.g. 'Unable to obtain password from user', 'Clock skew too great')
2. Verify principal and keytab path in the datasource form/config: test with `klist -kt keytab` and `kinit -kt keytab principal` on the worker host as the same OS user
3. Ensure the keytab file exists and is readable by the dolphinScheduler daemon user on every worker
4. Align krb5.conf realms/KDC and Hadoop hadoop.security.authentication=kerberos configuration; check NTP/clock sync
5. Regenerate keytab with supported encryption types (aes-256 etc.) if the KDC/types mismatch

Example fix

// before
principal: hive/_HOST@EXAMPLE.COM
keytab: /opt/keytab/hive.keytab   // file missing on worker
// after
klist -kt /etc/security/keytabs/hive.service.keytab
principal: hive/master@EXAMPLE.COM
keytab: /etc/security/keytabs/hive.service.keytab  // exists & readable by ds user

if (!new File(keytab).canRead()) throw new IllegalArgumentException("keytab unreadable: " + keytab);
if (principal == null || !principal.contains("@")) throw new IllegalArgumentException("bad principal: " + principal);
Runtime.getRuntime().exec(new String[]{"klist","-kt",keytab}).waitFor();

try {
  ugi = UserGroupInformationFactory.createKerberosUser(hadoopConf, principal, keytab);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("createUserGroupInformation fail")) {
    log.error("Kerberos login failed for {} — verify keytab/principal/KDC", principal, e.getCause());
  } else throw e;
}

When it happens

Trigger: login -> createKerberosUser when principal/keytab are wrong, keytab file does not exist or is unreadable, encryption types are unsupported, KDC is unreachable, or realm/defaultRealm mismatch causes authentication failure.

Common situations: Wrong principal name (case-sensitive, must match keytab entries); keytab path typo or missing file on worker nodes; expired keytab; kinit works interactively but service user lacks read permission on keytab; krb5.conf missing realms; clock skew > 5 min vs KDC.

Related errors

• Update Kerberos environment failed.
• OIDC_TOKEN_EXCHANGE_FAILED
• Error parsing ID token claims
• Unsupported authentication mode: " + redshiftConnectionParam
• SSH connection failed

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