apache/hadoop · critical · ServiceException

H02

H02

Error message

Kerberos initialization failed, {0}

What it means

With kerberos mode enabled, FileSystemAccessService calls UserGroupInformation.loginUserFromKeytab(principal, keytab) to log the daemon in. Error H02 ('Kerberos initialization failed') is thrown when that call raises an IOException; the IOException message is included as parameter {0} and chained as the cause. Startup aborts.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java:170

    if (security.equals("kerberos")) {
      String defaultName = getServer().getName();
      String keytab = System.getProperty("user.home") + "/" + defaultName + ".keytab";
      keytab = getServiceConfig().get(KERBEROS_KEYTAB, keytab).trim();
      if (keytab.length() == 0) {
        throw new ServiceException(FileSystemAccessException.ERROR.H01, KERBEROS_KEYTAB);
      }
      String principal = defaultName + "/localhost@LOCALHOST";
      principal = getServiceConfig().get(KERBEROS_PRINCIPAL, principal).trim();
      if (principal.length() == 0) {
        throw new ServiceException(FileSystemAccessException.ERROR.H01, KERBEROS_PRINCIPAL);
      }
      Configuration conf = new Configuration();
      conf.set(HADOOP_SECURITY_AUTHENTICATION, "kerberos");
      UserGroupInformation.setConfiguration(conf);
      try {
        UserGroupInformation.loginUserFromKeytab(principal, keytab);
      } catch (IOException ex) {
        throw new ServiceException(FileSystemAccessException.ERROR.H02, ex.getMessage(), ex);
      }
      LOG.info("Using FileSystemAccess Kerberos authentication, principal [{}] keytab [{}]", principal, keytab);
    } else if (security.equals("simple")) {
      Configuration conf = new Configuration();
      conf.set(HADOOP_SECURITY_AUTHENTICATION, "simple");
      UserGroupInformation.setConfiguration(conf);
      LOG.info("Using FileSystemAccess simple/pseudo authentication, principal [{}]", System.getProperty("user.name"));
    } else {
      throw new ServiceException(FileSystemAccessException.ERROR.H09, security);
    }

    String hadoopConfDirProp = getServiceConfig().get(HADOOP_CONF_DIR, getServer().getConfigDir());
    File hadoopConfDir = new File(hadoopConfDirProp).getAbsoluteFile();
    if (!hadoopConfDir.exists()) {
      hadoopConfDir = new File(getServer().getConfigDir()).getAbsoluteFile();
    }
    if (!hadoopConfDir.exists()) {
      throw new ServiceException(FileSystemAccessException.ERROR.H10, hadoopConfDir);

View on GitHub (pinned to 2add963021)

Solutions

1. Check the IOException message in parameter {0} - it states whether the keytab could not be found or the principal was missing
2. Verify the keytab contents with klist -kt /etc/security/keytabs/httpfs.keytab and confirm the principal matches httpfs.hadoop.authentication.kerberos.principal exactly
3. Test login manually: kinit -kt /etc/security/keytabs/httpfs.keytab httpfs/host@REALM
4. Fix permissions (keytab readable only by the httpfs user) and validate /etc/krb5.conf realm/KDC settings

Example fix

# before: principal does not match keytab -> H02 at startup
#   httpfs.hadoop.authentication.kerberos.principal = httpfs/_HOST@EXAMPLE.COM
#   keytab contains: httpfs/httpfs.example.com@EXAMPLE.COM
klist -kt /etc/security/keytabs/httpfs.keytab

# after: use the exact principal from the keytab
#   httpfs.hadoop.authentication.kerberos.principal = httpfs/httpfs.example.com@EXAMPLE.COM
kinit -kt /etc/security/keytabs/httpfs.keytab httpfs/httpfs.example.com@EXAMPLE.COM

// Preflight the kerberos login exactly the way the service will do it
Configuration c = new Configuration();
c.set("hadoop.security.authentication", "kerberos");
UserGroupInformation.setConfiguration(c);
UserGroupInformation.loginUserFromKeytab(principal, keytab); // throws here, not at server start

try {
  server.init();
} catch (ServerException ex) {
  if (ex.getCause() instanceof FileSystemAccessException
      && ((FileSystemAccessException) ex.getCause()).getError() == FileSystemAccessException.ERROR.H02) {
    Throwable io = ex.getCause().getCause(); // underlying IOException
    log.error("kerberos login failed: {}", io, ex);
  }
  throw ex;
}

When it happens

Trigger: httpfs.hadoop.authentication.type=kerberos and loginUserFromKeytab(principal, keytab) throws IOException: keytab file missing or unreadable, principal not present in the keytab, principal/keytab mismatch after re-keying, or a malformed krb5.conf/KDC problem surfaced as IOException during login.

Common situations: Wrong keytab path in httpfs.hadoop.authentication.kerberos.keytab; the principal string does not exactly match the keytab entry (wrong realm or host component); file permissions deny the httpfs daemon user; KDC unreachable or krb5.conf misconfigured.

Related errors

• H01
• Invalid SPNEGO sequence, 'WWW-Authenticate' header incorrect
• Invalid SPNEGO sequence, status code: {}
• Server asks us to fall back to SIMPLE auth, but this client
• Client did not send a token

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/a7c6325d8dd86662. Report an issue: GitHub.