What causes "StringFromGUID2" in java-native-access/jna?

Verify no modified/forked Ole32Util is in use where the buffer size was changed below 39

java-native-access/jna · error · RuntimeException

StringFromGUID2

Error message

StringFromGUID2

What it means

Ole32Util.getStringFromGUID converts a native GUID structure to its string form via Ole32 StringFromGUID2, which returns 0 when the supplied buffer is too small. The library throws a bare RuntimeException with the literal message 'StringFromGUID2' when the returned length is 0.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/Ole32Util.java:65

            throw new RuntimeException(hr.toString());
        }
        return lpiid;
    }

    /**
     * Convert a GUID into a string.
     *
     * @param guid GUID.
     *
     * @return String representation of a GUID.
     */
    public static String getStringFromGUID(GUID guid) {
        GUID pguid = new GUID(guid.getPointer());
        int max = 39;
        char[] lpsz = new char[max];
        int len = Ole32.INSTANCE.StringFromGUID2(pguid, lpsz, max);
        if (len == 0) {
            throw new RuntimeException("StringFromGUID2");
        }
        lpsz[len - 1] = 0;
        return Native.toString(lpsz);
    }

    /**
     * Generate a new GUID.
     *
     * @return New GUID.
     */
    public static GUID generateGUID() {
        GUID pguid = new GUID();
        HRESULT hr = Ole32.INSTANCE.CoCreateGuid(pguid);
        if (!hr.equals(W32Errors.S_OK)) {
            throw new RuntimeException(hr.toString());
        }
        return pguid;
    }

View on GitHub (pinned to d036ad9781)

Solutions

Verify no modified/forked Ole32Util is in use where the buffer size was changed below 39
Retry with a fresh GUID object; if persistent, check that the COM runtime (ole32.dll) is healthy on the host
Catch the RuntimeException and treat it as an unexpected native failure rather than an input problem

Example fix

// before
String s = Ole32Util.getStringFromGUID(guid);
// after
String s;
try {
    s = Ole32Util.getStringFromGUID(guid);
} catch (RuntimeException e) {
    throw new IllegalStateException("StringFromGUID2 conversion failed", e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (guid == null || guid.getPointer() == null) throw new IllegalArgumentException("GUID must be initialized");

Type guard

boolean isValidGuid(GUID g) { return g != null && g.getPointer() != null; }

Try / catch

try { return Ole32Util.getStringFromGUID(guid); } catch (RuntimeException e) { throw new IllegalStateException("StringFromGUID2 native conversion failed", e); }

Prevention

Treat this as an environment-level failure, not an input problem
Use stock JNA platform code — do not reduce the 39-char buffer in forks
Log the GUID object state when it occurs to aid native debugging

When it happens

Trigger: StringFromGUID2 returning 0, which in practice happens only if the char buffer is smaller than 39 characters; the library hardcodes max=39 so this is nearly unreachable from normal use — it signals a native/environmental failure of the COM conversion call.

Common situations: Rare: corrupted COM runtime state, exotic JVM/native setups where the fixed 39-char buffer assumption fails, or a bug in a forked/modified version of the helper that reduced the buffer size.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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