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

Component must be heavyweight

Error message

Component must be heavyweight

What it means

getComponentID/getWindowID reject lightweight components with this IllegalArgumentException because lightweight components have no native peer/window handle. JNA needs the underlying OS window ID, which only heavyweight (peer-backed) components possess.

Source

Thrown at src/com/sun/jna/Native.java:2546

        }
    }

    /** Provides separation of JAWT functionality for the sake of J2ME
     * ports which do not include AWT support.
     */
    private static class AWT {
        static long getWindowID(Window w) throws HeadlessException {
            return getComponentID(w);
        }
        // Declaring the argument as Object rather than Component avoids class not
        // found errors on phoneME foundation profile.
        static long getComponentID(Object o) throws HeadlessException {
            if (GraphicsEnvironment.isHeadless()) {
                throw new HeadlessException("No native windows when headless");
            }
            Component c = (Component)o;
            if (c.isLightweight()) {
                throw new IllegalArgumentException("Component must be heavyweight");
            }
            if (!c.isDisplayable())
                throw new IllegalStateException("Component must be displayable");
            // On X11 VMs prior to 1.5, the window must be visible
            if (Platform.isX11()
                && System.getProperty("java.version").startsWith("1.4")) {
                if (!c.isVisible()) {
                    throw new IllegalStateException("Component must be visible");
                }
            }
            // By this point, we're certain that Toolkit.loadLibraries() has
            // been called, thus avoiding AWT/JAWT link errors
            // (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6539705).
            return Native.getWindowHandle0(c);
        }
    }
}

View on GitHub (pinned to d036ad9781)

Solutions

  1. Pass a heavyweight component: the enclosing Window/Frame (e.g. frame) or a java.awt.Canvas.
  2. Call getComponentID on component.getHeavyweight ancestors — e.g. SwingUtilities.getWindowAncestor(panel).
  3. If a native surface is required inside a Swing UI, embed a Canvas (heavyweight) and use its ID.

Example fix

// before
long id = Native.getComponentID(jPanel); // lightweight
// after
long id = Native.getComponentID(SwingUtilities.getWindowAncestor(jPanel));
Defensive patterns

Strategy: validation

Validate before calling

static long requireHeavyweightId(Component c) {
    Window w = SwingUtilities.getWindowAncestor(c);
    if (w == null || GraphicsEnvironment.isHeadless()) {
        throw new IllegalStateException("Need a displayable heavyweight component");
    }
    return Native.getWindowID(w);
}

Type guard

boolean isHeavyweight(Component c) {
    return c instanceof Window || c instanceof java.applet.Applet
        || c instanceof java.awt.Canvas;
}

Try / catch

try {
    long id = Native.getComponentID(component);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must be heavyweight")) {
        component = SwingUtilities.getWindowAncestor(component);
        id = Native.getComponentID(component);
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Calling Native.getComponentID(...) passing a Swing component like JLabel, JPanel, JButton — all lightweight by default — instead of a native-peered component (Frame, Window, Canvas).

Common situations: Trying to render into or get the HWND of a JPanel/JLayeredPane; forgetting that Swing top-level containers (JFrame via its Window/Frame peer) are heavyweight while their contents are not.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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