alibaba/nacos · error · IllegalStateException

Malformed \uxxxx encoding.

Error message

Malformed \uxxxx encoding.

What it means

Thrown by OriginTrackedPropertiesPropertiesLoader's readUnicode() when a '\u' escape in a .properties file is followed by something other than four hex digits. Java properties require exactly four hex characters after \u.

Source

Thrown at sys/src/main/java/com/alibaba/nacos/sys/env/OriginTrackedPropertiesLoader.java:227

                this.columnNumber = -1;
                read(true);
            } else if (this.character == 'u') {
                readUnicode();
            }
        }
        
        private void readUnicode() throws IOException {
            this.character = 0;
            for (int i = 0; i < 4; i++) {
                int digit = this.reader.read();
                if (digit >= '0' && digit <= '9') {
                    this.character = (this.character << 4) + digit - '0';
                } else if (digit >= 'a' && digit <= 'f') {
                    this.character = (this.character << 4) + digit - 'a' + 10;
                } else if (digit >= 'A' && digit <= 'F') {
                    this.character = (this.character << 4) + digit - 'A' + 10;
                } else {
                    throw new IllegalStateException("Malformed \\uxxxx encoding.");
                }
            }
        }
        
        public boolean isWhiteSpace() {
            return !this.escaped
                && (this.character == ' ' || this.character == '\t' || this.character == '\f');
        }
        
        public boolean isEndOfFile() {
            return this.character == -1;
        }
        
        public boolean isEndOfLine() {
            return this.character == -1 || (!this.escaped && this.character == '\n');
        }
        
        public boolean isListDelimiter() {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Open the offending .properties file and locate the \u escape near the error.
2. Replace the malformed sequence with a valid four-hex-digit escape (e.g. \u00e9 for é), or use the literal UTF-8 character.
3. If '\u' was meant literally (e.g. in documentation text), escape the backslash as '\\u'.
4. Save the file as UTF-8 and use native characters instead of escapes where possible.
5. Run a properties linter/validator to catch stray escapes.

Example fix

# before (broken escape)
app.title=caf\u00eg

# after (valid escape or literal)
app.title=caf\u00e9
# or, in a UTF-8 file:
app.title=café

String v = Files.readString(Path.of(file));
java.util.regex.Matcher m = java.util.regex.Pattern.compile("\\\\u(?!([0-9a-fA-F]{4})).*").matcher(v);
if (m.find()) {
    throw new IllegalStateException("Malformed \\u escape near: " + m.group());
}

try {
    // load properties via OriginTrackedPropertiesLoader
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Malformed \\uxxxx")) {
        // point user at the offending .properties file and line
    }
    throw e;
}

When it happens

Trigger: A properties file contains a \uXXXX sequence where at least one of the four characters is not 0-9, a-f, or A-F (e.g. '\u00G1', '\u12', '\uXYZW'), or the sequence is truncated (fewer than four chars before EOF).

Common situations: Hand-edited properties with a malformed unicode escape; an editor or encoding-conversion tool corrupted a \u sequence; a file saved as Latin-1 with stray backslash-u sequences; copy/paste of a literal backslash-u meant as text.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• processors multiple must upper than 1
• processors scale must between 0 and 1
• Must be a file directory :
• nacos address
• Unsupported nacos deployment type {type}

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/21370a8438da1488. Report an issue: GitHub.