{"record":{"id":"84f3b3c9872aa6a9","repo":"apache/hadoop","slug":"bailing-out-since-native-library-couldn-t-be-loade-84f3b3","errorCode":null,"errorMessage":"Bailing out since native library couldn't be loaded","messagePattern":"Bailing out since native library couldn't be loaded","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/JniBasedUnixGroupsNetgroupMapping.java","lineNumber":53,"sourceCode":"\n/**\n * A JNI-based implementation of {@link GroupMappingServiceProvider} \n * that invokes libC calls to get the group\n * memberships of a given user.\n */\n@InterfaceAudience.LimitedPrivate({\"HDFS\", \"MapReduce\"})\n@InterfaceStability.Evolving\npublic class JniBasedUnixGroupsNetgroupMapping\n  extends JniBasedUnixGroupsMapping {\n  \n  private static final Logger LOG = LoggerFactory.getLogger(\n    JniBasedUnixGroupsNetgroupMapping.class);\n\n  native String[] getUsersForNetgroupJNI(String group);\n\n  static {\n    if (!NativeCodeLoader.isNativeCodeLoaded()) {\n      throw new RuntimeException(\"Bailing out since native library couldn't \" +\n        \"be loaded\");\n    }\n    LOG.debug(\"Using JniBasedUnixGroupsNetgroupMapping for Netgroup resolution\");\n  }\n\n  /**\n   * Gets unix groups and netgroups for the user.\n   *\n   * It gets all unix groups as returned by id -Gn but it\n   * only returns netgroups that are used in ACLs (there is\n   * no way to get all netgroups for a given user, see\n   * documentation for getent netgroup)\n   */\n  @Override\n  public List<String> getGroups(String user) throws IOException {\n    // parent gets unix groups\n    List<String> groups = new LinkedList<String>(super.getGroups(user));\n    NetgroupCache.getNetgroups(user, groups);","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/JniBasedUnixGroupsNetgroupMapping.java#L35-L71","documentation":"JniBasedUnixGroupsNetgroupMapping (netgroup resolution via getent-style JNI) has the same static guard as its parent: it requires NativeCodeLoader.isNativeCodeLoaded() or it throws RuntimeException during class initialization. It extends JniBasedUnixGroupsMapping and additionally declares getUsersForNetgroupJNI, so both the base class initializer and its own must see natives loaded. Typical symptom: ExceptionInInitializerError when Hadoop first resolves groups/netgroups after you configured this mapping.","triggerScenarios":"hadoop.security.group.mapping=org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMapping (or the ...WithFallback variant escalating to it) when libhadoop.so is not loadable — missing native dir in java.library.path, wrong architecture/glibc, or natives never built for the platform.","commonSituations":"HDFS ACLs or permissions using netgroups on hosts where natives are stripped (minimal container images); deployments that copied config from a native-enabled cluster onto JVM-only nodes; OS upgrades breaking glibc compatibility of the bundled .so.","solutions":["Fix native library loading: point java.library.path/LD_LIBRARY_PATH at $HADOOP_HOME/lib/native and confirm 'file libhadoop.so' matches your arch","Build platform-native artifacts (hadoop-common mvn -Pnative) or install your distribution's hadoop-native package on every node","If netgroups are required but natives impossible, use org.apache.hadoop.security.ShellBasedUnixGroupsNetgroupMapping (shells out to getent netgroup)","Prefer JniBasedUnixGroupsNetgroupMappingWithFallback so resolution degrades to shell instead of failing hard"],"exampleFix":"# before (core-site.xml)\n<property><name>hadoop.security.group.mapping</name>\n  <value>org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMapping</value></property>\n\n# after\n<property><name>hadoop.security.group.mapping</name>\n  <value>org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMappingWithFallback</value></property>","handlingStrategy":"fallback","validationCode":"if (conf.get(\"hadoop.security.group.mapping\", \"\")\n        .contains(\"Netgroup\")\n    && !NativeCodeLoader.isNativeCodeLoaded()) {\n  LOG.warn(\"Natives missing; netgroup JNI mapping unavailable — \"\n      + \"using ShellBasedUnixGroupsNetgroupMapping\");\n  conf.set(\"hadoop.security.group.mapping\",\n      \"org.apache.hadoop.security.ShellBasedUnixGroupsNetgroupMapping\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  Class<?> c = Class.forName(\n    \"org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMapping\");\n  return (GroupMappingServiceProvider) c.newInstance();\n} catch (ExceptionInInitializerError | NoClassDefFoundError e) {\n  // natives not loaded; fall back to shell-based netgroup mapping\n  return new ShellBasedUnixGroupsNetgroupMapping();\n}","preventionTips":["Run hadoop checknative on nodes that resolve netgroups","Choose ...WithFallback variants in cluster templates unless JNI is mandatory","Keep libhadoop.so deployable via config management so node refreshes don't silently drop it"],"tags":["native-library","jni","netgroups","group-mapping","hadoop"],"backgroundTag":"native-library-load-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}