java-native-access/jna · warning · UnsupportedOperationException

Window masking is not available

Error message

Window masking is not available

What it means

WindowUtils' base Provider.setMask throws UnsupportedOperationException because the default implementation provides no bitmap masking. Platform subclasses must override setMask; hitting this throw means the running platform's provider does not support window masking (translucent/shaped windows).

Source

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

                    lp.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);
                    root.setOpaque(Boolean.TRUE.equals(root.getClientProperty(TRANSPARENT_OLD_OPAQUE)));
                    root.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);
                    if (content != null) {
                        content.setOpaque(Boolean.TRUE.equals(content.getClientProperty(TRANSPARENT_OLD_OPAQUE)));
                        content.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);
                    }
                    bg = (Color)root.getClientProperty(TRANSPARENT_OLD_BG);
                    root.putClientProperty(TRANSPARENT_OLD_BG, null);
                }
            }
            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));
        }

View on GitHub (pinned to d036ad9781)

Solutions

1. Override setMask(Component, Raster) in your Provider subclass with platform-native masking
2. Verify the platform/JDK combination supports the required native peer (com.sun classes with proper JVM flags)
3. Wrap mask calls in try-catch for UnsupportedOperationException and fall back to undecorated full-opacity windows

Example fix

// before
WindowUtils.setWindowMask(window, shapeRaster);
// after
try {
    WindowUtils.setWindowMask(window, shapeRaster);
} catch (UnsupportedOperationException e) {
    logger.warn("Window masking unavailable on this platform", e);
}

try {
    WindowUtils.setWindowMask(window, raster);
} catch (UnsupportedOperationException e) {
    logger.warn("Window masking unsupported on this platform");
}

When it happens

Trigger: Calling setWindowMask(Component, Raster) (or Shape variant) with a WComponentPeer/Provider instance whose setMask was not overridden — i.e. on a platform lacking masking support in this library.

Common situations: Using WindowUtils on Linux/window managers without the needed X11 extension, or newer JDKs where the native peer hack no longer works; custom Provider subclasses that forgot to override setMask.

Related errors

• This platform is not supported, yet.
• No support (yet) for " + System.getProperty("os.name")
• Component must be heavyweight: " + w
• This pointer is opaque: " + this
• FileMonitor not implemented for " + os

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