java-native-access/jna · error · IllegalArgumentException

Component must be heavyweight: " + w

Error message

Component must be heavyweight: " + w

What it means

setWindowMask requires a heavyweight component; passing a lightweight component (Swing-only, no native peer) throws IllegalArgumentException. Bitmap masking works at the native window level, which lightweight components do not have.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/WindowUtils.java:581

            }
            w.setBackground(bg);
        }

        /** Override this method to provide bitmap masking of the given
         * heavyweight component.
         */
        protected void setMask(Component c, Raster raster) {
            throw new UnsupportedOperationException("Window masking is not available");
        }

        /**
         * Set the window mask based on the given Raster, which should
         * be treated as a bitmap (zero/nonzero values only). A value of
         * <code>null</code> means to remove the mask.
         */
        protected void setWindowMask(Component w, Raster raster) {
            if (w.isLightweight())
                throw new IllegalArgumentException("Component must be heavyweight: " + w);
            setMask(w, raster);
        }

        /** Set the window mask based on a {@link Shape}. */
        public void setWindowMask(Component w, Shape mask) {
            setWindowMask(w, toRaster(mask));
        }

        /**
         * Set the window mask based on an Icon. All non-transparent
         * pixels will be included in the mask.
         */
        public void setWindowMask(Component w, Icon mask) {
            setWindowMask(w, toRaster(w, mask));
        }

        /**
         * Use this method to ensure heavyweight popups are used in

View on GitHub (pinned to d036ad9781)

Solutions

1. Pass the top-level java.awt.Window (JFrame, JDialog, JWindow), not an inner Swing component
2. Check w.isLightweight() before calling and reject/warn early
3. Ensure the window is displayable/realized so its peer is heavyweight

Example fix

// before
WindowUtils.setWindowMask(myJPanel, raster);
// after
Window top = SwingUtilities.getWindowAncestor(myJPanel);
if (top != null && !top.isLightweight()) {
    WindowUtils.setWindowMask(top, raster);
}

if (w.isLightweight()) {
    throw new IllegalArgumentException("Window mask target must be heavyweight: " + w);
}

boolean isMaskable(Component c) {
    return !c.isLightweight() && c instanceof Window;
}

try {
    WindowUtils.setWindowMask(w, raster);
} catch (IllegalArgumentException e) {
    logger.warn("Target must be a heavyweight top-level window");
}

When it happens

Trigger: Calling WindowUtils.setWindowMask on a Swing JPanel or other lightweight component, or a Window whose peer is lightweight; isLightweight() returns true for the passed component.

Common situations: Applying masks to JWindow/JPanel instead of the top-level Window (JFrame/JDialog/Window); headless or unusual peers causing components to be reported lightweight; JDK changes altering heaviness.

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

• Window masking is not available
• This platform is not supported, yet.
• Set sun.java2d.noddraw=true to enable transparent windows
• Window must be a RootPaneContainer
• Area is not polygonal: " + area

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