java-native-access/jna · error · X11Exception

java.io.UnsupportedEncodingException (wrapped)

Error message

java.io.UnsupportedEncodingException (wrapped)

What it means

Window.getStringProperty (and similar string-returning property helpers) converts raw property bytes to a Java String using the "UTF8" charset. The JVM is required to support UTF-8, but if Charset.defaultCharset()/name lookup yields an unsupported name, UnsupportedEncodingException is thrown and wrapped in X11Exception with message "java.io.UnsupportedEncodingException (wrapped)".

Source

Thrown at contrib/x11/src/jnacontrib/x11/api/X.java:947

        }

        /**
         * Returns the property value as UTF8 string where every '\0' character is replaced by '.'.
         *
         * @param xa_prop_type property type
         * @param xa_prop_name property name
         * @return property value as UTF8 string where every '\0' character is replaced by '.'
         * @throws X11Exception thrown if X11 window errors occurred
         */
        public String getUtf8Property(X11.Atom xa_prop_type, X11.Atom xa_prop_name) throws X11Exception {
            try {
                byte[] property = getNullReplacedStringProperty(xa_prop_type, xa_prop_name);
                if( property == null ){
                    return null;
                }
                return new String(property, "UTF8");
            } catch (UnsupportedEncodingException e) {
                throw new X11Exception(e);
            }
        }

        /**
         * Returns the property value as UTF8 string where every '\0' character is replaced by '.'.
         *
         * @param xa_prop_type property type
         * @param xa_prop_name property name
         * @return property value as UTF8 string where every '\0' character is replaced by '.'
         * @throws X11Exception thrown if X11 window errors occurred
         */
        public String getUtf8Property(X11.Atom xa_prop_type, String xa_prop_name) throws X11Exception {
            return getUtf8Property(xa_prop_type, display.getAtom(xa_prop_name));
        }

        /**
         * Returns the property value as UTF8 string list
         *

View on GitHub (pinned to d036ad9781)

Solutions

1. Use a standard full JDK/JRE (Oracle, OpenJDK, Temurin) where UTF-8 is always supported
2. Replace the literal "UTF8" with java.nio.charset.StandardCharsets.UTF_8, which never throws
3. Catch X11Exception around property reads and surface a clear runtime-environment error
4. Verify Charset.isSupported("UTF8") at startup in constrained environments

Example fix

// before
return new String(property, "UTF8");
// after
return new String(property, StandardCharsets.UTF_8); // never throws UnsupportedEncodingException

if (!Charset.isSupported("UTF8")) {
    throw new IllegalStateException("JRE lacks UTF-8 charset; property reads will fail");
}

try {
    name = win.getStringProperty(atom);
} catch (X11Exception e) {
    if (e.getCause() instanceof UnsupportedEncodingException) {
        throw new IllegalStateException("Replace JRE: UTF-8 charset missing", e);
    }
    throw e;
}

When it happens

Trigger: Calling any Window method that returns a String property (e.g. getStringProperty / window-name getters) on a JVM that lacks the UTF8 charset mapping.

Common situations: Running on a severely stripped-down JRE, an unusual JVM build without full charsets, or code run under a JVM whose rt.jar/charset provider excludes UTF8 (very rare).

Related errors

• Can't open X Display
• Attempting to retrieve VisualID from a null Visual
• Can't open X Display
• X Display is null
• Cannot get window manager info properties. (_NET_SUPPORTING_

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