{"record":{"id":"c88ebfeb41a76863","repo":"java-native-access/jna","slug":"java-io-unsupportedencodingexception-wrapped","errorCode":null,"errorMessage":"java.io.UnsupportedEncodingException (wrapped)","messagePattern":"java\\.io\\.UnsupportedEncodingException \\(wrapped\\)","errorType":"exception","errorClass":"X11Exception","httpStatus":null,"severity":"error","filePath":"contrib/x11/src/jnacontrib/x11/api/X.java","lineNumber":947,"sourceCode":"        }\n\n        /**\n         * Returns the property value as UTF8 string where every '\\0' character is replaced by '.'.\n         *\n         * @param xa_prop_type property type\n         * @param xa_prop_name property name\n         * @return property value as UTF8 string where every '\\0' character is replaced by '.'\n         * @throws X11Exception thrown if X11 window errors occurred\n         */\n        public String getUtf8Property(X11.Atom xa_prop_type, X11.Atom xa_prop_name) throws X11Exception {\n            try {\n                byte[] property = getNullReplacedStringProperty(xa_prop_type, xa_prop_name);\n                if( property == null ){\n                    return null;\n                }\n                return new String(property, \"UTF8\");\n            } catch (UnsupportedEncodingException e) {\n                throw new X11Exception(e);\n            }\n        }\n\n        /**\n         * Returns the property value as UTF8 string where every '\\0' character is replaced by '.'.\n         *\n         * @param xa_prop_type property type\n         * @param xa_prop_name property name\n         * @return property value as UTF8 string where every '\\0' character is replaced by '.'\n         * @throws X11Exception thrown if X11 window errors occurred\n         */\n        public String getUtf8Property(X11.Atom xa_prop_type, String xa_prop_name) throws X11Exception {\n            return getUtf8Property(xa_prop_type, display.getAtom(xa_prop_name));\n        }\n\n        /**\n         * Returns the property value as UTF8 string list\n         *","sourceCodeStart":929,"sourceCodeEnd":965,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/x11/src/jnacontrib/x11/api/X.java#L929-L965","documentation":"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)\".","triggerScenarios":"Calling any Window method that returns a String property (e.g. getStringProperty / window-name getters) on a JVM that lacks the UTF8 charset mapping.","commonSituations":"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).","solutions":["Use a standard full JDK/JRE (Oracle, OpenJDK, Temurin) where UTF-8 is always supported","Replace the literal \"UTF8\" with java.nio.charset.StandardCharsets.UTF_8, which never throws","Catch X11Exception around property reads and surface a clear runtime-environment error","Verify Charset.isSupported(\"UTF8\") at startup in constrained environments"],"exampleFix":"// before\nreturn new String(property, \"UTF8\");\n// after\nreturn new String(property, StandardCharsets.UTF_8); // never throws UnsupportedEncodingException","handlingStrategy":"try-catch","validationCode":"if (!Charset.isSupported(\"UTF8\")) {\n    throw new IllegalStateException(\"JRE lacks UTF-8 charset; property reads will fail\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    name = win.getStringProperty(atom);\n} catch (X11Exception e) {\n    if (e.getCause() instanceof UnsupportedEncodingException) {\n        throw new IllegalStateException(\"Replace JRE: UTF-8 charset missing\", e);\n    }\n    throw e;\n}","preventionTips":["Use StandardCharsets.UTF_8 instead of the \"UTF8\" literal in patches","Run standard OpenJDK/Temurin builds, not stripped runtimes","Assert charset support at application startup","Treat charset errors as environment bugs, not transient"],"tags":["x11","encoding","utf8","jre"],"backgroundTag":"unsupported-encoding","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}