json-path/JsonPath · error · JsonPathException

Unable to parse unicode value: %s

Error message

Unable to parse unicode value: %s

What it means

Utils.unescape() processes JSON string escape sequences, including \uXXXX. When the four hex digits after \u are not valid hexadecimal (e.g. \u12zz), Integer.parseInt(...,16) throws NumberFormatException, which is rethrown as JsonPathException with this message. It indicates malformed input or an incorrectly pre-processed string being fed to the parser.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/Utils.java:193

        }
        int len = str.length();
        StringWriter writer = new StringWriter(len);
        StringBuilder unicode = new StringBuilder(4);
        boolean hadSlash = false;
        boolean inUnicode = false;
        for (int i = 0; i < len; i++) {
            char ch = str.charAt(i);
            if (inUnicode) {
                unicode.append(ch);
                if (unicode.length() == 4) {
                    try {
                        int value = Integer.parseInt(unicode.toString(), 16);
                        writer.write((char) value);
                        unicode.setLength(0);
                        inUnicode = false;
                        hadSlash = false;
                    } catch (NumberFormatException nfe) {
                        throw new JsonPathException("Unable to parse unicode value: " + unicode, nfe);
                    }
                }
                continue;
            }
            if (hadSlash) {
                hadSlash = false;
                switch (ch) {
                    case '\\':
                        writer.write('\\');
                        break;
                    case '\'':
                        writer.write('\'');
                        break;
                    case '\"':
                        writer.write('"');
                        break;
                    case 'r':
                        writer.write('\r');

View on GitHub (pinned to 62a4c9f0f6)

Solutions

  1. Fix the source string so every \u escape is followed by exactly 4 hexadecimal digits.
  2. Unescape/massage the text correctly before parsing (account for double escaping: '\\u0041' in raw bytes).
  3. Validate input with a strict JSON parser first to get a precise location of the malformed escape.

Example fix

// before
String bad = "{\"name\": \"\\u12zz\"}"; // \u12zz is not valid hex
// after
String good = "{\"name\": \"\\u12FF\"}"; // exactly 4 hex digits
Defensive patterns

Strategy: try-catch

Validate before calling

java.util.regex.Pattern HEX = java.util.regex.Pattern.compile("\\\\\\\\u[0-9a-fA-F]{4}");
// reject any \u not followed by exactly 4 hex digits before parsing
if (!HEX.matcher(input).find() && input.contains("\\u")) {
    throw new IllegalArgumentException("Malformed unicode escape in input");
}

Try / catch

try {
    DocumentContext ctx = JsonPath.parse(raw);
} catch (JsonPathException e) {
    if (e.getMessage().startsWith("Unable to parse unicode value")) {
        // fix escaping / re-decode source, then retry once
    } else throw e;
}

Prevention

When it happens

Trigger: Parsing a JSON document (or a string containing escapes) where a \u escape is followed by fewer than 4 hex characters or invalid hex characters, e.g. "\uGG12" or a truncated "\u12" at the end of a string.

Common situations: Consuming hand-built or double-escaped JSON, copying payloads from logs where backslashes were mangled, strings that were already decoded once so remaining '\u' is literal data rather than a valid escape, or non-JSON text fed into JsonPath.parse().

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of json-path/JsonPath@62a4c9f0f6 (2026-09-11). Data as JSON: /api/errors/46823032af6faf30. Report an issue: GitHub.