java-native-access/jna · error · IllegalArgumentException

Window must be a RootPaneContainer

Error message

Window must be a RootPaneContainer

What it means

setWindowTransparent requires the Window to be a RootPaneContainer (JFrame, JDialog, JWindow) because it manipulates the content pane's background alpha. Passing a plain Window, Frame, or Dialog that does not implement RootPaneContainer throws IllegalArgumentException('Window must be a RootPaneContainer').

Source

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

                    user.UpdateLayeredWindow(hWnd, screenDC, winLoc, winSize, memDC,
                                             srcLoc, 0, blend, WinUser.ULW_ALPHA);
                } finally {
                    user.ReleaseDC(null, screenDC);
                    if (memDC != null && oldBitmap != null) {
                        gdi.SelectObject(memDC, oldBitmap);
                    }
                }
            }
        }

        /** Note that w32 does <em>not</em> paint window decorations when
         * the window is transparent.
         */
        @Override
        public void setWindowTransparent(final Window w,
                                         final boolean transparent) {
            if (!(w instanceof RootPaneContainer)) {
                throw new IllegalArgumentException("Window must be a RootPaneContainer");
            }
            if (!isWindowAlphaSupported()) {
                throw new UnsupportedOperationException("Set sun.java2d.noddraw=true to enable transparent windows");
            }
            boolean isTransparent = w.getBackground() != null
                && w.getBackground().getAlpha() == 0;
            if (transparent == isTransparent)
                return;
            whenDisplayable(w, new Runnable() {
                @Override
                public void run() {
                    User32 user = User32.INSTANCE;
                    HWND hWnd = getHWnd(w);
                    int flags = user.GetWindowLong(hWnd, WinUser.GWL_EXSTYLE);
                    JRootPane root = ((RootPaneContainer)w).getRootPane();
                    JLayeredPane lp = root.getLayeredPane();
                    Container content = root.getContentPane();
                    if (content instanceof W32TransparentContentPane) {

View on GitHub (pinned to d036ad9781)

Solutions

1. Use a JFrame, JDialog, or JWindow instead of plain Window/Frame/Dialog.
2. Check `w instanceof RootPaneContainer` before calling and handle unsupported window types.
3. For non-Swing windows, use a different transparency mechanism (e.g. Java 7+ AWTUtilities/setWindowOpacity equivalents).
4. Cast safely after an instanceof check to access the root pane.

Example fix

// before
Window w = new Window(owner);
WindowUtils.setWindowTransparent(w, true); // IllegalArgumentException
// after
JWindow w = new JWindow(owner);
if (w instanceof RootPaneContainer) {
    WindowUtils.setWindowTransparent(w, true);
}

if (!(w instanceof RootPaneContainer)) { throw new IllegalArgumentException("Need JFrame/JDialog/JWindow"); }

boolean isTransparencyCapable(Window w) { return w instanceof RootPaneContainer; }

try { WindowUtils.setWindowTransparent(w, true); } catch (IllegalArgumentException e) { // convert to JFrame/JWindow or skip }

When it happens

Trigger: Calling WindowUtils.setWindowTransparent(new Window(owner), true) or passing a java.awt.Frame/Dialog instance that is not a JFrame/JDialog/JWindow.

Common situations: Trying to make raw AWT windows transparent; creating Window objects programmatically instead of Swing top-levels; helper code typed as java.awt.Window receiving non-Swing windows at runtime.

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

• Set sun.java2d.noddraw=true to enable transparent windows
• Area is not polygonal: " + area
• Component must be heavyweight: " + w
• No support for " + os
• Property Accessor name must start with 'get', or set the ano

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