java-native-access/jna · error · RuntimeException

RuntimeException(hr.toString())

Error message

RuntimeException(hr.toString())

What it means

Ole32Util.getGUIDFromString parses a GUID/CLSID string (e.g. '{XXXXXXXX-XXXX-...}') into a native GUID structure via Ole32 IIDFromString. If the native call returns any HRESULT other than S_OK, the library throws a bare RuntimeException whose message is just the HRESULT toString (e.g. '0x80004005'), losing the context that GUID parsing failed.

Source

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

/**
 * Ole32 Utility API.
 * @author dblock[at]dblock.org
 */
public abstract class Ole32Util {

    /**
     * Convert a string to a GUID.
     *
     * @param guidString String representation of a GUID, including { }.
     *
     * @return A GUID.
     */
    public static GUID getGUIDFromString(String guidString) {
        GUID lpiid = new GUID();
        HRESULT hr = Ole32.INSTANCE.IIDFromString(guidString, lpiid);
        if (!hr.equals(W32Errors.S_OK)) {
            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");

View on GitHub (pinned to d036ad9781)

Solutions

1. Fix the input string to be a valid GUID in the form {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} (braces optional but grouping and hex digits must be correct)
2. Validate the string against a GUID regex before calling getGUIDFromString
3. Catch the RuntimeException and inspect the message HRESULT to confirm ERROR_INVALID_PARAMETER-style failure meaning malformed input

Example fix

// before
GUID guid = Ole32Util.getGUIDFromString(guidString);
// after
if (!guidString.matches("^\\{?[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}\\}?$")) {
    throw new IllegalArgumentException("Not a valid GUID string: " + guidString);
}
GUID guid = Ole32Util.getGUIDFromString(guidString);

private static final java.util.regex.Pattern GUID = java.util.regex.Pattern.compile("^\\{?[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}\\}?$");
if (guidString == null || !GUID.matcher(guidString.trim()).matches()) throw new IllegalArgumentException("invalid GUID: " + guidString);

boolean isGuidString(String s) { return s != null && GUID.matcher(s.trim()).matches(); }

try { GUID g = Ole32Util.getGUIDFromString(s); } catch (RuntimeException e) { throw new IllegalArgumentException("malformed GUID string: " + s, e); }

When it happens

Trigger: Calling getGUIDFromString with a string that is not a well-formed GUID: missing braces, wrong digit/hex characters, wrong dash grouping, extra whitespace, or an empty string — any input IIDFromString cannot parse.

Common situations: Hardcoded CLSIDs copied from documentation or IDL files with typos; GUID strings read from config/registry that were stored in a different format (no braces, lowercase '0x' prefixes); user-supplied class IDs passed through from application config.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• StringFromGUID2
• getUnknownId: <formatMessageFromHR>
• Error occured when trying get Unknown Id
• pDisp (IDispatch) parameter is null!
• Failed to create WbemLocator object.

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