{"record":{"id":"97399942c36cf6ff","repo":"apache/hadoop","slug":"nativeio-was-not-loaded","errorCode":null,"errorMessage":"NativeIO was not loaded","messagePattern":"NativeIO was not loaded","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/nativeio/NativeIO.java","lineNumber":369,"sourceCode":"        } catch (Throwable t) {\n          // This can happen if the user has an older version of libhadoop.so\n          // installed - in this case we can continue without native IO\n          // after warning\n          PerformanceAdvisory.LOG.debug(\"Unable to initialize NativeIO libraries\", t);\n        }\n      }\n    }\n\n    /**\n     * @return Return true if the JNI-based native IO extensions are available.\n     */\n    public static boolean isAvailable() {\n      return NativeCodeLoader.isNativeCodeLoaded() && nativeLoaded;\n    }\n\n    private static void assertCodeLoaded() throws IOException {\n      if (!isAvailable()) {\n        throw new IOException(\"NativeIO was not loaded\");\n      }\n    }\n\n    /**\n     * Wrapper around open(2) .\n     * @param path input path.\n     * @param flags input flags.\n     * @param mode input mode.\n     * @return FileDescriptor.\n     * @throws IOException raised on errors performing I/O.\n     */\n    public static native FileDescriptor open(String path, int flags, int mode) throws IOException;\n    /** Wrapper around fstat(2) */\n    private static native Stat fstat(FileDescriptor fd) throws IOException;\n    /** Wrapper around stat(2). */\n    private static native Stat stat(String path) throws IOException;\n\n    /** Native chmod implementation. On UNIX, it is a wrapper around chmod(2) */","sourceCodeStart":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/nativeio/NativeIO.java#L351-L387","documentation":"NativeIO.assertCodeLoaded() throws IOException(\"NativeIO was not loaded\") when the JNI-based native IO layer is unavailable: either NativeCodeLoader reports no native libhadoop loaded, or NativeIO's own initializer failed. Every JNI-dependent NativeIO entry point (mlock, fstat, getStat, chmod wrappers, renameTo0) funnels through this guard, so any of them can surface this error.","triggerScenarios":"Calling a JNI-dependent NativeIO method on a JVM where libhadoop.so/hadoop.dll was never loaded or failed to load: java.library.path not pointing at $HADOOP_HOME/lib/native, missing or wrong-arch .so, glibc incompatibility, unsupported platform, or a broken Hadoop distribution layout.","commonSituations":"LD_LIBRARY_PATH/-Djava.library.path unset in custom launch scripts; running on platforms without prebuilt natives (some ARM/macOS setups); Windows without hadoop.dll or the VC++ runtime; containers with a stripped-down Hadoop install.","solutions":["Check availability up front with NativeIO.isAvailable() and read the NativeCodeLoader startup banner — it logs exactly which library failed and why.","Point the JVM at the natives: -Djava.library.path=$HADOOP_HOME/lib/native (or export LD_LIBRARY_PATH) and verify libhadoop.so exists for your OS/arch with ldd.","If natives are missing or incompatible, install/rebuild the correct package (distro package or mvn native compile) matching arch and glibc.","If native IO is optional in your path, branch to a pure-Java implementation (java.nio.file) when isAvailable() is false."],"exampleFix":"// before\nNativeIO.chmod(path, 0644); // IOException: NativeIO was not loaded\n\n// after\nif (NativeIO.isAvailable()) {\n  NativeIO.chmod(path, 0644);\n} else {\n  Files.setPosixFilePermissions(Paths.get(path),\n      PosixFilePermissions.fromString(\"rw-r--r--\"));\n}","handlingStrategy":"validation","validationCode":"if (!NativeIO.isAvailable()) {\n  // skip native-dependent calls; route to a java.nio.file implementation\n}","typeGuard":null,"tryCatchPattern":"try {\n  NativeIO.getStat(path);\n} catch (IOException e) {\n  if (\"NativeIO was not loaded\".equals(e.getMessage())) {\n    // fall back: Files.readAttributes(Paths.get(path), ...)\n  } else { throw e; }\n}","preventionTips":["Assert NativeIO.isAvailable() once at startup and read the NativeCodeLoader banner.","Bake -Djava.library.path into the launch script instead of relying on ambient env.","Keep a pure-Java fallback for every NativeIO call you use (chmod/fstat/stat all have java.nio equivalents)."],"tags":["native-io","jni","java-library-path","hadoop-common"],"backgroundTag":"native-library-not-loaded","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}