java-native-access/jna · error · IllegalArgumentException

Invalid library name "<libname>"

Error message

Invalid library name "<libname>"

What it means

Library.Handler's constructor validates the native library name and throws this IllegalArgumentException when the name is null-trimmed to an empty string (non-null but blank). JNA requires either a real library name/path or null to mean 'link against the current process'.

Source

Thrown at src/com/sun/jna/Library.java:179

                this.handler = handler;
                this.function = function;
                this.isVarArgs = isVarArgs;
                this.options = options;
                this.parameterTypes = parameterTypes;
                this.methodHandle = null;
            }
        }

        private final NativeLibrary nativeLibrary;
        private final Class<?> interfaceClass;
        // Library invocation options
        private final Map<String, Object> options;
        private final InvocationMapper invocationMapper;
        private final Map<Method, FunctionInfo> functions = new WeakHashMap<>();
        public Handler(String libname, Class<?> interfaceClass, Map<String, ?> options) {

            if (libname != null && "".equals(libname.trim())) {
                throw new IllegalArgumentException("Invalid library name \"" + libname + "\"");
            }

            if (!interfaceClass.isInterface()) {
                throw new IllegalArgumentException(libname + " does not implement an interface: " + interfaceClass.getName());
            }

            this.interfaceClass = interfaceClass;
            this.options = new HashMap<>(options);
            int callingConvention = AltCallingConvention.class.isAssignableFrom(interfaceClass)
                                  ? Function.ALT_CONVENTION
                                  : Function.C_CONVENTION;
            if (this.options.get(OPTION_CALLING_CONVENTION) == null) {
                this.options.put(OPTION_CALLING_CONVENTION, Integer.valueOf(callingConvention));
            }
            if (this.options.get(OPTION_CLASSLOADER) == null) {
                this.options.put(OPTION_CLASSLOADER, interfaceClass.getClassLoader());
            }
            this.nativeLibrary = NativeLibrary.getInstance(libname, this.options);

View on GitHub (pinned to d036ad9781)

Solutions

  1. Pass a real library name (without platform prefix/suffix) or full path to Native.load.
  2. If you intend to bind to the current process, pass null explicitly, not "".
  3. Trim/validate the configured name and fail fast with a clear config error before calling Native.load.

Example fix

// before
String lib = System.getProperty("lib.name"); // may be ""
MyLib lib = Native.load(lib, MyLib.class);
// after
String lib = System.getProperty("lib.name", "mylib").trim();
MyLib lib = Native.load(lib.isEmpty() ? null : lib, MyLib.class);
Defensive patterns

Strategy: validation

Validate before calling

static String requireLibName(String name) {
  if (name == null || name.trim().isEmpty())
    throw new IllegalArgumentException("Native library name must be non-blank (use null explicitly for current process)");
  return name.trim();
}

Try / catch

try {
  MyLib lib = Native.load(name, MyLib.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid library name")) {
    throw new IllegalStateException("Configured library name is blank; check the lib.name setting", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: Native.load("", Iface.class) or Native.load(" ", Iface.class); loading a library via a config/property that resolved to whitespace; calling Native.loadLibrary with a blank name.

Common situations: Library name pulled from an environment variable or properties file that is blank; string concatenation producing an empty name; mistaking "" for the null meaning of 'current process'.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/942c7a718c38ad0d. Report an issue: GitHub.