libgdx/libgdx · error · GdxRuntimeException

Encoding '

Error message

Encoding '

What it means

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.

Source

Thrown at backends/gdx-backends-gwt/src/com/badlogic/gdx/backends/gwt/GwtFileHandle.java:133

	/** Returns a buffered stream for reading this file as bytes.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public BufferedInputStream read (int bufferSize) {
		return new BufferedInputStream(read(), bufferSize);
	}

	/** Returns a reader for reading this file as characters.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public Reader reader () {
		return new InputStreamReader(read());
	}

	/** Returns a reader for reading this file as characters.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public Reader reader (String charset) {
		try {
			return new InputStreamReader(read(), charset);
		} catch (UnsupportedEncodingException e) {
			throw new GdxRuntimeException("Encoding '" + charset + "' not supported", e);
		}
	}

	/** Returns a buffered reader for reading this file as characters.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public BufferedReader reader (int bufferSize) {
		return new BufferedReader(reader(), bufferSize);
	}

	/** Returns a buffered reader for reading this file as characters.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public BufferedReader reader (int bufferSize, String charset) {
		return new BufferedReader(reader(charset), bufferSize);
	}

	/** Reads the entire file into a string using the platform's default charset.
	 * @throws GdxRuntimeException if the file handle represents a directory, doesn't exist, or could not be read. */
	public String readString () {

View on GitHub (pinned to 97f4086187)

Solutions

1. Use the charset-less overloads reader() / readString(string, append) which use the default (UTF-8) decoding, and store assets as UTF-8.
2. Standardize on the canonical name "UTF-8" (uppercase, hyphenated) everywhere a charset string is passed.
3. Trim/validate the charset string before passing it if it comes from configuration files.
4. 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.

Example fix

// before
Reader r = handle.reader("utf8"); // may throw Encoding 'utf8' not supported

// after
Reader r = handle.reader("UTF-8");
// or simply rely on default UTF-8
Reader r = handle.reader();

// canonicalize before passing a charset name
String safeCharset = (charset == null || charset.trim().isEmpty()) ? "UTF-8" : charset.trim();
if (!"UTF-8".equals(safeCharset) && !"ISO-8859-1".equals(safeCharset)) {
    throw new IllegalArgumentException("Use UTF-8 assets on GWT: " + safeCharset);
}
return fh.reader("UTF-8");

try {
    return fh.reader(charset);
} catch (GdxRuntimeException e) {
    if (e.getCause() instanceof UnsupportedEncodingException) {
        return fh.reader(); // fall back to default UTF-8 decoding
    }
    throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• libGDX requires Android API Level " + MINIMUM_SDK + " or lat
• Cannot get the sibling of the root.
• Error reading file: " + file + " (" + type + ")
• Error memory mapping file: " + this + " (" + type + ")
• Error listing children: " + file + " (" + type + ")

AI-assisted analysis of libgdx/libgdx@97f4086187 (2026-08-14). Data as JSON: /api/errors/1bd05b1f4ebac828. Report an issue: GitHub.