apache/druid · error · IllegalStateException

Failed to authenticate user principal [%s] with keytab [%s]

Error message

Failed to authenticate user principal [%s] with keytab [%s]

What it means

KerberosAuthenticator's client-side login helper catches an IOException raised by Hadoop's UserGroupInformation login/keytab re-login machinery and rethrows it as an ISE. It means UGI could not authenticate the configured internal client principal against the client keytab.

Source

Thrown at extensions-core/druid-kerberos/src/main/java/org/apache/druid/security/kerberos/DruidKerberosUtil.java:119

        if (UserGroupInformation.getCurrentUser().hasKerberosCredentials() == false
            || !UserGroupInformation.getCurrentUser().getUserName().equals(internalClientPrincipal)) {
          log.info("trying to authenticate user [%s] with keytab [%s]", internalClientPrincipal, internalClientKeytab);
          UserGroupInformation.loginUserFromKeytab(internalClientPrincipal, internalClientKeytab);
          return;
        }
        //try to relogin in case the TGT expired
        if (UserGroupInformation.isLoginKeytabBased()) {
          log.info("Re-Login from key tab [%s] with principal [%s]", internalClientKeytab, internalClientPrincipal);
          UserGroupInformation.getLoginUser().checkTGTAndReloginFromKeytab();
          return;
        } else if (UserGroupInformation.isLoginTicketBased()) {
          log.info("Re-Login from Ticket cache");
          UserGroupInformation.getLoginUser().reloginFromTicketCache();
          return;
        }
      }
      catch (IOException e) {
        throw new ISE(
            e,
            "Failed to authenticate user principal [%s] with keytab [%s]",
            internalClientPrincipal,
            internalClientKeytab
        );
      }
    }
  }

  public static boolean needToSendCredentials(CookieStore cookieStore, URI uri)
  {
    return getAuthCookie(cookieStore, uri) == null;
  }

  public static HttpCookie getAuthCookie(CookieStore cookieStore, URI uri)
  {
    if (cookieStore == null) {
      return null;

View on GitHub (pinned to 9b90983fd2)

Solutions

Verify druid.auth.kerberos.clientKeytab/clientPrincipal (internal client settings) are correct and the keytab exists and is readable
Run kinit -kt <keytab> <principal> on the host to confirm the principal is valid against the KDC
Check KDC reachability and NTP/clock synchronization
Inspect the wrapped IOException cause for the concrete JAAS failure

Example fix

// before
// principal changed after rotation
props.setProperty("druid.auth.kerberos.internal.clientPrincipal", "old_user@EXAMPLE.COM");
// after
props.setProperty("druid.auth.kerberos.internal.clientPrincipal", "druid@EXAMPLE.COM");

Defensive patterns

Strategy: try-catch

Validate before calling

// before use, verify principal against KDC:
// kinit -kt /path/client.keytab druid@EXAMPLE.COM && klist

Try / catch

try {
  kerberosUtil.authenticateIfRequired();
} catch (ISE e) {
  log.error("Kerberos client login failed; check keytab/principal/KDC", e.getCause());
  throw e;
}

Prevention

Keep client principal/keytab config in sync with KDC rotations
Monitor NTP skew cluster-wide; clock drift breaks Kerberos
Alert on KDC unavailability before it surfaces as login IOExceptions

When it happens

Trigger: authenticateIfRequired() triggers UGI.loginUserFromKeytab / relogin and the underlying JAAS login throws IOException (unreadable keytab, wrong principal, KDC unreachable, clock skew).

Common situations: druid.client-internal kerberos keytab/principal misconfigured; keytab rotated and principal removed; KDC temporarily down; ticket renewal failing due to time drift between nodes.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/ed9c9a47a27ff69a. Report an issue: GitHub.