java-native-access/jna · error · java.lang.NullPointerException

String must not be null

Error message

String must not be null

What it means

NativeString's constructor throws NullPointerException when the Java String is null. A native string requires actual characters to copy into allocated memory; JNA refuses to silently map null to an empty or zero pointer.

Source

Thrown at src/com/sun/jna/NativeString.java:78

     * @param wide whether to store the String as <code>wchar_t</code>
     */
    public NativeString(String string, boolean wide) {
        this(string, wide ? WIDE_STRING : Native.getDefaultStringEncoding());
    }

    /** Create a native string as a NUL-terminated array of
     * <code>wchar_t</code>.
     */
    public NativeString(WString string) {
        this(string.toString(), WIDE_STRING);
    }

    /** Create a native string (NUL-terminated array of <code>char</code>),
     * using the requested encoding.
     */
    public NativeString(String string, String encoding) {
        if (string == null) {
            throw new NullPointerException("String must not be null");
        }
        // Allocate the memory to hold the string.  Note, we have to
        // make this 1 element longer in order to accommodate the terminating
        // NUL (which is generated in Pointer.setString()).
        this.encoding = encoding;
        if (WIDE_STRING.equals(this.encoding)) {
            int len = (string.length() + 1 ) * Native.WCHAR_SIZE;
            pointer = new StringMemory(len);
            pointer.setWideString(0, string);
        } else {
            byte[] data = Native.getBytes(string, encoding);
            pointer = new StringMemory(data.length + 1);
            pointer.write(0, data, 0, data.length);
            pointer.setByte(data.length, (byte)0);
        }
    }

    @Override

View on GitHub (pinned to d036ad9781)

Solutions

1. Check the string for null before creating the NativeString or invoking the function
2. Pass an explicit empty string ("") if the native side expects a valid string
3. Use a mapped null handling (custom TypeMapper that maps null to a NULL Pointer) if null is a valid native value
4. In Structure fields of type String, ensure setField/constructor values are non-null or use Pointer NULL explicitly

Example fix

// before
NativeString ns = new NativeString(maybeNull, "UTF-8");
// after
NativeString ns = maybeNull != null
    ? new NativeString(maybeNull, "UTF-8")
    : null; // or new NativeString("", "UTF-8")

if (s == null) {
    s = ""; // or reject
}

static String requireNonNullString(String s) {
    if (s == null) throw new IllegalArgumentException("string required");
    return s;
}

try {
    NativeString ns = new NativeString(s, "UTF-8");
} catch (NullPointerException e) {
    // s was null; substitute "" or a NULL Pointer
}

When it happens

Trigger: Creating new NativeString(null, encoding) directly, or passing a null String to a mapped function argument where the parameter type is String and no null-substitution is configured.

Common situations: Null values coming from parsing/user input passed straight into native calls; API surfaces that allow null Strings reaching a structure field of native-string type.

Related errors

• setValue must not be called with type set to NULL
• Function name must not be null
• null passed to getNativeLibrary
• Function name may not be null
• String initializer must be non-null

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