{"record":{"id":"f3130ac89590b741","repo":"apache/hadoop","slug":"native-runtime-library-not-loaded","errorCode":null,"errorMessage":"Native runtime library not loaded","messagePattern":"Native runtime library not loaded","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-nativetask/src/main/java/org/apache/hadoop/mapred/nativetask/NativeRuntime.java","lineNumber":66,"sourceCode":"\n  private static Configuration conf = new Configuration();\n\n  static {\n    try {\n      System.loadLibrary(\"nativetask\");\n      LOG.info(\"Nativetask JNI library loaded.\");\n      nativeLibraryLoaded = true;\n    } catch (final Throwable t) {\n      // Ignore failures\n      LOG.error(\"Failed to load nativetask JNI library with error: \" + t);\n      LOG.info(\"java.library.path=\" + System.getProperty(\"java.library.path\"));\n      LOG.info(\"LD_LIBRARY_PATH=\" + System.getenv(\"LD_LIBRARY_PATH\"));\n    }\n  }\n\n  private static void assertNativeLibraryLoaded() {\n    if (!nativeLibraryLoaded) {\n      throw new RuntimeException(\"Native runtime library not loaded\");\n    }\n  }\n\n  public static boolean isNativeLibraryLoaded() {\n    return nativeLibraryLoaded;\n  }\n\n  public static void configure(Configuration jobConf) {\n    assertNativeLibraryLoaded();\n    conf = new Configuration(jobConf);\n    conf.set(Constants.NATIVE_HADOOP_VERSION, VersionInfo.getVersion());\n    JNIConfigure(ConfigUtil.toBytes(conf));\n  }\n\n  /**\n   * create native object We use it to create native handlers\n   */\n  public synchronized static long createNativeObject(String clazz) {","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-nativetask/src/main/java/org/apache/hadoop/mapred/nativetask/NativeRuntime.java#L48-L84","documentation":"NativeRuntime's static initializer sets nativeLibraryLoaded only when the JNI library loads; every stateful entry point (configure, createNativeObject, ...) first calls assertNativeLibraryLoaded(), which throws RuntimeException('Native runtime library not loaded') when the flag is false. This guards against calling JNI functions through an uninitialized runtime. Callers are expected to gate on isNativeLibraryLoaded() first.","triggerScenarios":"Calling NativeRuntime.configure(jobConf), createNativeObject(...), or any guarded API after the static load of libnativetask.so failed (missing/incompatible .so), without checking isNativeLibraryLoaded().","commonSituations":"Library code or platform implementations invoking NativeRuntime directly on nodes with broken native installs; test harnesses running on developer machines without the native library compiled; calling createNativeObject for a handler after an earlier load failure in the same JVM.","solutions":["Guard every NativeRuntime call with if (NativeRuntime.isNativeLibraryLoaded()) and provide a Java fallback path","Fix the underlying load: install the matching libnativetask.so and set java.library.path / LD_LIBRARY_PATH (confirm with 'hadoop checknative')","In tests, skip native-dependent cases (e.g. Assume/AssumeTrue on isNativeLibraryLoaded) instead of letting the RuntimeException fail the run"],"exampleFix":"// before\nNativeRuntime.configure(jobConf); // RuntimeException if load failed\n\n// after\nif (NativeRuntime.isNativeLibraryLoaded()) {\n  NativeRuntime.configure(jobConf);\n} else {\n  throw new InvalidJobConfException(\"NativeRuntime cannot be loaded, check libnativetask.so\");\n}","handlingStrategy":"validation","validationCode":"if (NativeRuntime.isNativeLibraryLoaded()) {\n  NativeRuntime.configure(jobConf);\n  long addr = NativeRuntime.createNativeObject(handlerName);\n} else {\n  throw new IllegalStateException(\n      \"libnativetask.so not loaded; fix java.library.path/LD_LIBRARY_PATH before using native APIs\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  NativeRuntime.configure(conf);\n} catch (RuntimeException e) {\n  if (\"Native runtime library not loaded\".equals(e.getMessage())) {\n    // skip native path; fall back to the Java implementation\n  } else { throw e; }\n}","preventionTips":["Never call NativeRuntime entry points without an isNativeLibraryLoaded() guard","In tests, use assumeTrue(NativeRuntime.isNativeLibraryLoaded()) for native-only cases","Treat load failures as fatal-for-feature, not fatal-for-job: provide the Java fallback path"],"tags":["nativetask","native-library","jni","guard-clause"],"backgroundTag":"native-library-load-failure","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}