java-native-access/jna · error · UnsupportedOperationException

This X11 display does not provide a 32-bit visual

Error message

This X11 display does not provide a 32-bit visual

What it means

Guard exception in setWindowAlpha: it fires when the X11 server provides no 32-bit (ARGB) visual, which JNA requires for per-window alpha compositing. Root cause is the display/server configuration (e.g. plain 16/24-bit visuals, no composite manager), not the alpha value passed in.

Solutions

1. Call WindowUtils.isWindowAlphaSupported() first and degrade gracefully to opaque rendering
2. Use a compositing window manager and ensure the X server offers a 32-bit visual (xdpyinfo | grep 'depth 32')
3. On unsupported displays, skip alpha effects instead of calling setWindowAlpha

When it happens

Trigger: Thrown at contrib/platform/src/com/sun/jna/platform/WindowUtils.java:1849 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

                }
            }
            return win;
        }

        private static X11.Window getDrawable(Component w) {
            int id = (int)Native.getComponentID(w);
            if (id == X11.None)
                return null;
            return new X11.Window(id);
        }

        private static final long OPAQUE = 0xFFFFFFFFL;
        private static final String OPACITY = "_NET_WM_WINDOW_OPACITY";

        @Override
        public void setWindowAlpha(final Window w, final float alpha) {
            if (!isWindowAlphaSupported()) {
                throw new UnsupportedOperationException("This X11 display does not provide a 32-bit visual");
            }
            Runnable action = new Runnable() {
                @Override
                public void run() {
                    X11 x11 = X11.INSTANCE;
                    Display dpy = x11.XOpenDisplay(null);
                    if (dpy == null)
                        return;
                    try {
                        X11.Window win = getDrawable(w);
                        if (alpha == 1f) {
                            x11.XDeleteProperty(dpy, win,
                                                x11.XInternAtom(dpy, OPACITY,
                                                                false));
                        }
                        else {
                            int opacity = (int)((long)(alpha * OPAQUE) & 0xFFFFFFFF);
                            IntByReference patom = new IntByReference(opacity);

View on GitHub (pinned to d036ad9781)