apache/maven · error · IllegalArgumentException

Unable to parse unicode value: %s

Error message

Unable to parse unicode value: %s

What it means

Maven's properties loader (MavenProperties, the java-properties parser) handles \uXXXX escapes: after a backslash-u it accumulates exactly four characters and converts them with Integer.parseInt(digits, 16). If those four characters are not valid hexadecimal digits, the NumberFormatException is rethrown as IllegalArgumentException 'Unable to parse unicode value: <digits>'. This is the standard .properties escaping rule, identical to java.util.Properties: a backslash before 'u' always starts a unicode escape.

Source

Thrown at compat/maven-embedder/src/main/java/org/apache/maven/cli/props/MavenProperties.java:603

        boolean hadSlash = false;
        boolean inUnicode = false;
        for (int i = 0; i < sz; i++) {
            char ch = str.charAt(i);
            if (inUnicode) {
                // if in unicode, then we're reading unicode
                // values in somehow
                unicode.append(ch);
                if (unicode.length() == UNICODE_LEN) {
                    // unicode now contains the four hex digits
                    // which represents our unicode character
                    try {
                        int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
                        out.append((char) value);
                        unicode.setLength(0);
                        inUnicode = false;
                        hadSlash = false;
                    } catch (NumberFormatException nfe) {
                        throw new IllegalArgumentException("Unable to parse unicode value: " + unicode, nfe);
                    }
                }
                continue;
            }

            if (hadSlash) {
                // handle an escaped value
                hadSlash = false;
                switch (ch) {
                    case '\\':
                        out.append('\\');
                        break;
                    case '\'':
                        out.append('\'');
                        break;
                    case '\"':
                        out.append('"');
                        break;

View on GitHub (pinned to e4093d4e12)

Solutions

1. Escape backslashes: write C:\\users\\john (doubled) in the properties file.
2. Prefer forward slashes for paths in properties files: C:/users/john — Java APIs accept them on Windows.
3. Find the offending line: search the loaded file(s) for the regex \\u followed by a non-4-hex sequence.
4. If a genuine unicode escape was intended, supply exactly four hex digits (\u00e9).

Example fix

# before (properties file)
output.dir=C:\users\john\out

# after
output.dir=C:/users/john/out
# or
output.dir=C:\\users\\john\\out

// Validate a properties file before handing it to Maven tooling
static void assertNoBadUnicodeEscape(Path f) throws IOException {
    Pattern bad = Pattern.compile("\\\\u(?![0-9a-fA-F]{4})");
    for (String line : Files.readAllLines(f)) {
        String l = line.replaceAll("\\\\\\\\", ""); // skip escaped backslashes
        if (bad.matcher(l).find()) {
            throw new IllegalArgumentException("Stray backslash-u in " + f + ": " + line);
        }
    }
}

try {
    props.load(reader);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to parse unicode value")) {
        // report the offending file/line: a \u not followed by 4 hex digits; fix escaping and reload
    }
    throw e;
}

When it happens

Trigger: A properties file (e.g. loaded by Maven tooling) containing a Windows path like C:\users\john — the sequence \user makes the parser read 'sers' as the four hex digits and fail. Any stray backslash immediately followed by 'u' that is not a genuine 4-hex-digit escape (e.g. \utility, C:\usr, log paths like ...\upload).

Common situations: Windows machines writing absolute paths into properties files with single backslashes. Copying Windows examples into cross-platform config. Config generators that interpolate backslashes without doubling them.

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

• Unable to parse unicode value: {}
• Cannot read project model from interpolating filter of seria
• Cannot read toolchains file at " + userToolchainsFile.getAbs
• Duplicated tag: 'extensions'
• Expected root element 'extensions' but found no element at a

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/5774c7479a20daa3. Report an issue: GitHub.