apache/hadoop · critical · ServiceException

H09

H09

Error message

Invalid FileSystemAccess security mode [{0}]

What it means

FileSystemAccessService only supports two authentication modes: 'simple' (default) and 'kerberos'. The value of httpfs.hadoop.authentication.type is trimmed and compared case-sensitively; any other value causes error H09 ('Invalid FileSystemAccess security mode') at service init and the httpfs server fails to start.

Source

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

      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);
    }
    try {
      serviceHadoopConf = loadHadoopConf(hadoopConfDir);
      fileSystemConf = getNewFileSystemConfiguration();
    } catch (IOException ex) {
      throw new ServiceException(FileSystemAccessException.ERROR.H11, ex.toString(), ex);
    }

    if (LOG.isDebugEnabled()) {

View on GitHub (pinned to 2add963021)

Solutions

1. Set httpfs.hadoop.authentication.type to exactly 'simple' or 'kerberos' (lowercase, no whitespace)
2. If you want no kerberos, set it to 'simple' or remove the property entirely (default is simple)
3. Restart httpfs and confirm the startup log shows the expected authentication mode

Example fix

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

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

String mode = conf.get("httpfs.hadoop.authentication.type", "simple").trim();
if (!mode.equals("simple") && !mode.equals("kerberos")) {
  throw new IllegalStateException("httpfs.hadoop.authentication.type must be 'simple' or 'kerberos', got: '" + mode + "'");
}

When it happens

Trigger: httpfs.hadoop.authentication.type set to anything other than the exact lowercase strings 'kerberos' or 'simple' - e.g. 'Kerberos' (wrong case), 'kerboros' (typo), 'sasl', or an empty string after trimming (an unset property defaults to 'simple' and is safe).

Common situations: Case mismatch when hand-editing httpfs-site.xml; typos; copying a hadoop.security.authentication value ('kerberos' vs 'SIMPLE'-style casing from other components) into the httpfs property; leaving an empty value while 'trying to disable' the setting.

Related errors

• Server asks us to fall back to SIMPLE auth, but this client
• ${method} authentication is not enabled. Available:${enable
• AuthenticationMethod.TOKEN + " authentication requires a sec
• Auth '{}' not of expected form scheme:auth
• Undefined property: signature.secret.file

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