apache/hadoop · error · RuntimeException

Native runtime library not loaded

Error message

Native runtime library not loaded

What it means

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.

Source

Thrown at hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-nativetask/src/main/java/org/apache/hadoop/mapred/nativetask/NativeRuntime.java:66

  private static Configuration conf = new Configuration();

  static {
    try {
      System.loadLibrary("nativetask");
      LOG.info("Nativetask JNI library loaded.");
      nativeLibraryLoaded = true;
    } catch (final Throwable t) {
      // Ignore failures
      LOG.error("Failed to load nativetask JNI library with error: " + t);
      LOG.info("java.library.path=" + System.getProperty("java.library.path"));
      LOG.info("LD_LIBRARY_PATH=" + System.getenv("LD_LIBRARY_PATH"));
    }
  }

  private static void assertNativeLibraryLoaded() {
    if (!nativeLibraryLoaded) {
      throw new RuntimeException("Native runtime library not loaded");
    }
  }

  public static boolean isNativeLibraryLoaded() {
    return nativeLibraryLoaded;
  }

  public static void configure(Configuration jobConf) {
    assertNativeLibraryLoaded();
    conf = new Configuration(jobConf);
    conf.set(Constants.NATIVE_HADOOP_VERSION, VersionInfo.getVersion());
    JNIConfigure(ConfigUtil.toBytes(conf));
  }

  /**
   * create native object We use it to create native handlers
   */
  public synchronized static long createNativeObject(String clazz) {

View on GitHub (pinned to 2add963021)

Solutions

1. Guard every NativeRuntime call with if (NativeRuntime.isNativeLibraryLoaded()) and provide a Java fallback path
2. Fix the underlying load: install the matching libnativetask.so and set java.library.path / LD_LIBRARY_PATH (confirm with 'hadoop checknative')
3. In tests, skip native-dependent cases (e.g. Assume/AssumeTrue on isNativeLibraryLoaded) instead of letting the RuntimeException fail the run

Example fix

// before
NativeRuntime.configure(jobConf); // RuntimeException if load failed

// after
if (NativeRuntime.isNativeLibraryLoaded()) {
  NativeRuntime.configure(jobConf);
} else {
  throw new InvalidJobConfException("NativeRuntime cannot be loaded, check libnativetask.so");
}

if (NativeRuntime.isNativeLibraryLoaded()) {
  NativeRuntime.configure(jobConf);
  long addr = NativeRuntime.createNativeObject(handlerName);
} else {
  throw new IllegalStateException(
      "libnativetask.so not loaded; fix java.library.path/LD_LIBRARY_PATH before using native APIs");
}

try {
  NativeRuntime.configure(conf);
} catch (RuntimeException e) {
  if ("Native runtime library not loaded".equals(e.getMessage())) {
    // skip native path; fall back to the Java implementation
  } else { throw e; }
}

When it happens

Trigger: Calling NativeRuntime.configure(jobConf), createNativeObject(...), or any guarded API after the static load of libnativetask.so failed (missing/incompatible .so), without checking isNativeLibraryLoaded().

Common situations: 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.

Related errors

• Bailing out since native library couldn't be loaded
• Bailing out since native library couldn't be loaded
• NativeIO is not available.
• Native object create failed, class: {}
• NativeRuntime cannot be loaded, please check that libnativet

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