{"record":{"id":"cb9e858d1d97a47b","repo":"java-native-access/jna","slug":"component-must-be-heavyweight","errorCode":null,"errorMessage":"Component must be heavyweight","messagePattern":"Component must be heavyweight","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Native.java","lineNumber":2546,"sourceCode":"        }\n    }\n\n    /** Provides separation of JAWT functionality for the sake of J2ME\n     * ports which do not include AWT support.\n     */\n    private static class AWT {\n        static long getWindowID(Window w) throws HeadlessException {\n            return getComponentID(w);\n        }\n        // Declaring the argument as Object rather than Component avoids class not\n        // found errors on phoneME foundation profile.\n        static long getComponentID(Object o) throws HeadlessException {\n            if (GraphicsEnvironment.isHeadless()) {\n                throw new HeadlessException(\"No native windows when headless\");\n            }\n            Component c = (Component)o;\n            if (c.isLightweight()) {\n                throw new IllegalArgumentException(\"Component must be heavyweight\");\n            }\n            if (!c.isDisplayable())\n                throw new IllegalStateException(\"Component must be displayable\");\n            // On X11 VMs prior to 1.5, the window must be visible\n            if (Platform.isX11()\n                && System.getProperty(\"java.version\").startsWith(\"1.4\")) {\n                if (!c.isVisible()) {\n                    throw new IllegalStateException(\"Component must be visible\");\n                }\n            }\n            // By this point, we're certain that Toolkit.loadLibraries() has\n            // been called, thus avoiding AWT/JAWT link errors\n            // (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6539705).\n            return Native.getWindowHandle0(c);\n        }\n    }\n}\n","sourceCodeStart":2528,"sourceCodeEnd":2564,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L2528-L2564","documentation":"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.","triggerScenarios":"Calling Native.getComponentID(...) passing a Swing component like JLabel, JPanel, JButton — all lightweight by default — instead of a native-peered component (Frame, Window, Canvas).","commonSituations":"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.","solutions":["Pass a heavyweight component: the enclosing Window/Frame (e.g. frame) or a java.awt.Canvas.","Call getComponentID on component.getHeavyweight ancestors — e.g. SwingUtilities.getWindowAncestor(panel).","If a native surface is required inside a Swing UI, embed a Canvas (heavyweight) and use its ID."],"exampleFix":"// before\nlong id = Native.getComponentID(jPanel); // lightweight\n// after\nlong id = Native.getComponentID(SwingUtilities.getWindowAncestor(jPanel));","handlingStrategy":"validation","validationCode":"static long requireHeavyweightId(Component c) {\n    Window w = SwingUtilities.getWindowAncestor(c);\n    if (w == null || GraphicsEnvironment.isHeadless()) {\n        throw new IllegalStateException(\"Need a displayable heavyweight component\");\n    }\n    return Native.getWindowID(w);\n}","typeGuard":"boolean isHeavyweight(Component c) {\n    return c instanceof Window || c instanceof java.applet.Applet\n        || c instanceof java.awt.Canvas;\n}","tryCatchPattern":"try {\n    long id = Native.getComponentID(component);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"must be heavyweight\")) {\n        component = SwingUtilities.getWindowAncestor(component);\n        id = Native.getComponentID(component);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Always resolve to the nearest Window via SwingUtilities.getWindowAncestor before requesting an ID.","Never pass JPanel/JLabel/JButton directly; use the top-level Window or a Canvas.","Ensure the component is displayable (added to a visible hierarchy) before lookup.","Unit-test native-ID extraction with real top-level windows, not lightweight fixtures."],"tags":["jna","awt","lightweight-component","window-handle"],"backgroundTag":"invalid-argument-value","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}