{"record":{"id":"a7c6325d8dd86662","repo":"apache/hadoop","slug":"h02","errorCode":"H02","errorMessage":"Kerberos initialization failed, {0}","messagePattern":"Kerberos initialization failed, (.+?)","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java","lineNumber":170,"sourceCode":"    if (security.equals(\"kerberos\")) {\n      String defaultName = getServer().getName();\n      String keytab = System.getProperty(\"user.home\") + \"/\" + defaultName + \".keytab\";\n      keytab = getServiceConfig().get(KERBEROS_KEYTAB, keytab).trim();\n      if (keytab.length() == 0) {\n        throw new ServiceException(FileSystemAccessException.ERROR.H01, KERBEROS_KEYTAB);\n      }\n      String principal = defaultName + \"/localhost@LOCALHOST\";\n      principal = getServiceConfig().get(KERBEROS_PRINCIPAL, principal).trim();\n      if (principal.length() == 0) {\n        throw new ServiceException(FileSystemAccessException.ERROR.H01, KERBEROS_PRINCIPAL);\n      }\n      Configuration conf = new Configuration();\n      conf.set(HADOOP_SECURITY_AUTHENTICATION, \"kerberos\");\n      UserGroupInformation.setConfiguration(conf);\n      try {\n        UserGroupInformation.loginUserFromKeytab(principal, keytab);\n      } catch (IOException ex) {\n        throw new ServiceException(FileSystemAccessException.ERROR.H02, ex.getMessage(), ex);\n      }\n      LOG.info(\"Using FileSystemAccess Kerberos authentication, principal [{}] keytab [{}]\", principal, keytab);\n    } else if (security.equals(\"simple\")) {\n      Configuration conf = new Configuration();\n      conf.set(HADOOP_SECURITY_AUTHENTICATION, \"simple\");\n      UserGroupInformation.setConfiguration(conf);\n      LOG.info(\"Using FileSystemAccess simple/pseudo authentication, principal [{}]\", System.getProperty(\"user.name\"));\n    } else {\n      throw new ServiceException(FileSystemAccessException.ERROR.H09, security);\n    }\n\n    String hadoopConfDirProp = getServiceConfig().get(HADOOP_CONF_DIR, getServer().getConfigDir());\n    File hadoopConfDir = new File(hadoopConfDirProp).getAbsoluteFile();\n    if (!hadoopConfDir.exists()) {\n      hadoopConfDir = new File(getServer().getConfigDir()).getAbsoluteFile();\n    }\n    if (!hadoopConfDir.exists()) {\n      throw new ServiceException(FileSystemAccessException.ERROR.H10, hadoopConfDir);","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java#L152-L188","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the IOException message in parameter {0} - it states whether the keytab could not be found or the principal was missing","Verify the keytab contents with klist -kt /etc/security/keytabs/httpfs.keytab and confirm the principal matches httpfs.hadoop.authentication.kerberos.principal exactly","Test login manually: kinit -kt /etc/security/keytabs/httpfs.keytab httpfs/host@REALM","Fix permissions (keytab readable only by the httpfs user) and validate /etc/krb5.conf realm/KDC settings"],"exampleFix":"# before: principal does not match keytab -> H02 at startup\n#   httpfs.hadoop.authentication.kerberos.principal = httpfs/_HOST@EXAMPLE.COM\n#   keytab contains: httpfs/httpfs.example.com@EXAMPLE.COM\nklist -kt /etc/security/keytabs/httpfs.keytab\n\n# after: use the exact principal from the keytab\n#   httpfs.hadoop.authentication.kerberos.principal = httpfs/httpfs.example.com@EXAMPLE.COM\nkinit -kt /etc/security/keytabs/httpfs.keytab httpfs/httpfs.example.com@EXAMPLE.COM","handlingStrategy":"validation","validationCode":"// Preflight the kerberos login exactly the way the service will do it\nConfiguration c = new Configuration();\nc.set(\"hadoop.security.authentication\", \"kerberos\");\nUserGroupInformation.setConfiguration(c);\nUserGroupInformation.loginUserFromKeytab(principal, keytab); // throws here, not at server start","typeGuard":null,"tryCatchPattern":"try {\n  server.init();\n} catch (ServerException ex) {\n  if (ex.getCause() instanceof FileSystemAccessException\n      && ((FileSystemAccessException) ex.getCause()).getError() == FileSystemAccessException.ERROR.H02) {\n    Throwable io = ex.getCause().getCause(); // underlying IOException\n    log.error(\"kerberos login failed: {}\", io, ex);\n  }\n  throw ex;\n}","preventionTips":["Run kinit -kt <keytab> <principal> as the httpfs user before starting the daemon","Grant the keytab 400 permissions owned by the httpfs user only","Keep principal/keytab in sync when keys are rolled; re-verify after each KDC re-key","Validate /etc/krb5.conf points at reachable KDCs from the httpfs host"],"tags":["httpfs","kerberos","authentication","kdc","keytab"],"backgroundTag":"kerberos-login-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}