{"record":{"id":"b5cc8439580d225e","repo":"apache/hadoop","slug":"h09","errorCode":"H09","errorMessage":"Invalid FileSystemAccess security mode [{0}]","messagePattern":"Invalid FileSystemAccess security mode \\[(.+?)\\]","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":179,"sourceCode":"      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);\n    }\n    try {\n      serviceHadoopConf = loadHadoopConf(hadoopConfDir);\n      fileSystemConf = getNewFileSystemConfiguration();\n    } catch (IOException ex) {\n      throw new ServiceException(FileSystemAccessException.ERROR.H11, ex.toString(), ex);\n    }\n\n    if (LOG.isDebugEnabled()) {","sourceCodeStart":161,"sourceCodeEnd":197,"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#L161-L197","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set httpfs.hadoop.authentication.type to exactly 'simple' or 'kerberos' (lowercase, no whitespace)","If you want no kerberos, set it to 'simple' or remove the property entirely (default is simple)","Restart httpfs and confirm the startup log shows the expected authentication mode"],"exampleFix":"<!-- before -->\n<property><name>httpfs.hadoop.authentication.type</name><value>Kerberos</value></property>\n\n<!-- after -->\n<property><name>httpfs.hadoop.authentication.type</name><value>kerberos</value></property>","handlingStrategy":"validation","validationCode":"String mode = conf.get(\"httpfs.hadoop.authentication.type\", \"simple\").trim();\nif (!mode.equals(\"simple\") && !mode.equals(\"kerberos\")) {\n  throw new IllegalStateException(\"httpfs.hadoop.authentication.type must be 'simple' or 'kerberos', got: '\" + mode + \"'\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a config-management template that only permits the two legal values","Prefer unsetting the property over blanking it when you want 'simple'","Diff httpfs-site.xml against httpfs-default.xml after upgrades to catch invalid values"],"tags":["httpfs","configuration","security","authentication","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}