apache/hadoop · critical · ServiceException

H01

H01

Error message

Service property [{0}] not defined

What it means

When httpfs.hadoop.authentication.type is set to 'kerberos', FileSystemAccessService resolves the keytab via the httpfs.hadoop.authentication.kerberos.keytab property (default ${user.home}/httpfs.keytab). Error H01 ('Service property not defined') is thrown at service init if the trimmed keytab value is empty, i.e. the property was explicitly set to a blank value.

Source

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

  private Configuration fileSystemConf;

  private AtomicInteger unmanagedFileSystems = new AtomicInteger();

  private ConcurrentHashMap<String, CachedFileSystem> fsCache =
    new ConcurrentHashMap<String, CachedFileSystem>();

  private long purgeTimeout;

  @Override
  protected void init() throws ServiceException {
    LOG.info("Using FileSystemAccess JARs version [{}]", VersionInfo.getVersion());
    String security = getServiceConfig().get(AUTHENTICATION_TYPE, "simple").trim();
    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");

View on GitHub (pinned to 2add963021)

Solutions

1. Set httpfs.hadoop.authentication.kerberos.keytab in httpfs-site.xml to the absolute path of the httpfs keytab
2. Ensure the keytab file exists and is readable by the user running httpfs
3. Also set httpfs.hadoop.authentication.kerberos.principal (the next check throws H01 for it too)
4. Restart httpfs and confirm the 'Using FileSystemAccess Kerberos authentication' log line

Example fix

<!-- before -->
<property><name>httpfs.hadoop.authentication.type</name><value>kerberos</value></property>
<property><name>httpfs.hadoop.authentication.kerberos.keytab</name><value></value></property>

<!-- after -->
<property><name>httpfs.hadoop.authentication.type</name><value>kerberos</value></property>
<property><name>httpfs.hadoop.authentication.kerberos.keytab</name><value>/etc/security/keytabs/httpfs.keytab</value></property>
<property><name>httpfs.hadoop.authentication.kerberos.principal</name><value>httpfs/_HOST@EXAMPLE.COM</value></property>

String type = conf.get("httpfs.hadoop.authentication.type", "simple").trim();
if (type.equals("kerberos")) {
  String keytab = conf.get("httpfs.hadoop.authentication.kerberos.keytab", "").trim();
  if (keytab.isEmpty() || !new java.io.File(keytab).canRead()) {
    throw new IllegalStateException("httpfs.hadoop.authentication.kerberos.keytab must be a readable path");
  }
}

When it happens

Trigger: httpfs.hadoop.authentication.type=kerberos and httpfs.hadoop.authentication.kerberos.keytab is present in httpfs-site.xml but its value trims to an empty string; startup then aborts during FileSystemAccessService.init().

Common situations: A kerberos deployment template was copied with the keytab value left blank; an operator set the property to '' while migrating from the deprecated httpfs.authentication.kerberos.keytab key; environment substitution produced an empty value.

Related errors

• Server asks us to fall back to SIMPLE auth, but this client
• Running in secure mode, but config doesn't have a keytab for
• Kerberos required for secure registry access
• Security is enabled but block access tokens (via dfs.block.a
• Security is enabled but block access tokens (via dfs.block.a

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