{"record":{"id":"1bd05b1f4ebac828","repo":"libgdx/libgdx","slug":"encoding","errorCode":null,"errorMessage":"Encoding '","messagePattern":"Encoding '","errorType":"exception","errorClass":"GdxRuntimeException","httpStatus":null,"severity":"error","filePath":"backends/gdx-backends-gwt/src/com/badlogic/gdx/backends/gwt/GwtFileHandle.java","lineNumber":133,"sourceCode":"\t/** Returns a buffered stream for reading this file as bytes.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic BufferedInputStream read (int bufferSize) {\n\t\treturn new BufferedInputStream(read(), bufferSize);\n\t}\n\n\t/** Returns a reader for reading this file as characters.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic Reader reader () {\n\t\treturn new InputStreamReader(read());\n\t}\n\n\t/** Returns a reader for reading this file as characters.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic Reader reader (String charset) {\n\t\ttry {\n\t\t\treturn new InputStreamReader(read(), charset);\n\t\t} catch (UnsupportedEncodingException e) {\n\t\t\tthrow new GdxRuntimeException(\"Encoding '\" + charset + \"' not supported\", e);\n\t\t}\n\t}\n\n\t/** Returns a buffered reader for reading this file as characters.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic BufferedReader reader (int bufferSize) {\n\t\treturn new BufferedReader(reader(), bufferSize);\n\t}\n\n\t/** Returns a buffered reader for reading this file as characters.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic BufferedReader reader (int bufferSize, String charset) {\n\t\treturn new BufferedReader(reader(charset), bufferSize);\n\t}\n\n\t/** Reads the entire file into a string using the platform's default charset.\n\t * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */\n\tpublic String readString () {","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/libgdx/libgdx/blob/97f40861878058087be0685ca167ddfde132134b/backends/gdx-backends-gwt/src/com/badlogic/gdx/backends/gwt/GwtFileHandle.java#L115-L151","documentation":"GwtFileHandle.reader(String charset) wraps new InputStreamReader(read(), charset); when the JVM/GWT-emulated charset support does not recognize the name, java.io.UnsupportedEncodingException is caught and rethrown as this GdxRuntimeException. The underlying stream was opened successfully — only the character decoding name is wrong.","triggerScenarios":"Calling reader(charset) or readString(charset) with an unsupported/misspelled charset name (e.g. \"UTF8 \" with trailing space, \"utf-8\" variants the emulated layer rejects, or exotic charsets not compiled into the GWT emulation).","commonSituations":"Copy-pasted charset strings with typos or BOM/whitespace; code assuming every java.nio charset exists in GWT's reduced Character/charset emulation; reading legacy files encoded in non-UTF-8 encodings on the web build.","solutions":["Use the charset-less overloads reader() / readString(string, append) which use the default (UTF-8) decoding, and store assets as UTF-8.","Standardize on the canonical name \"UTF-8\" (uppercase, hyphenated) everywhere a charset string is passed.","Trim/validate the charset string before passing it if it comes from configuration files.","If a non-UTF-8 asset is required, re-encode it to UTF-8 at build time instead of relying on runtime charset support in GWT."],"exampleFix":"// before\nReader r = handle.reader(\"utf8\"); // may throw Encoding 'utf8' not supported\n\n// after\nReader r = handle.reader(\"UTF-8\");\n// or simply rely on default UTF-8\nReader r = handle.reader();","handlingStrategy":"validation","validationCode":"// canonicalize before passing a charset name\nString safeCharset = (charset == null || charset.trim().isEmpty()) ? \"UTF-8\" : charset.trim();\nif (!\"UTF-8\".equals(safeCharset) && !\"ISO-8859-1\".equals(safeCharset)) {\n    throw new IllegalArgumentException(\"Use UTF-8 assets on GWT: \" + safeCharset);\n}\nreturn fh.reader(\"UTF-8\");","typeGuard":null,"tryCatchPattern":"try {\n    return fh.reader(charset);\n} catch (GdxRuntimeException e) {\n    if (e.getCause() instanceof UnsupportedEncodingException) {\n        return fh.reader(); // fall back to default UTF-8 decoding\n    }\n    throw e;\n}","preventionTips":["Standardize all text assets as UTF-8 and use the no-charset overloads.","Never build charset strings from user/config input without trimming and validating.","Re-encode legacy non-UTF-8 assets at build time instead of decoding them in GWT."],"tags":["gwt","libgdx","charset","encoding","reader"],"backgroundTag":null,"analyzedSha":"97f40861878058087be0685ca167ddfde132134b","analyzedAt":"2026-08-14T10:52:53.492Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}