What causes "JsonPathException" in json-path/JsonPath?

Use StandardCharsets.UTF_8.name() (or another guaranteed standard charset) instead of free-form strings.

json-path/JsonPath · error · JsonPathException

JsonPathException

Error message

JsonPathException

What it means

JakartaJsonProvider.parse(InputStream, charset) delegates to a Reader-based parse; if constructing the InputStreamReader throws UnsupportedEncodingException (an invalid charset name), it is rethrown as JsonPathException. This is a configuration/argument error, not a JSON syntax problem.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/json/JakartaJsonProvider.java:86

    }

    @Override
    public Object parse(String json) throws InvalidJsonException {
        return parse(new StringReader(json));
    }

    @Override
    public Object parse(byte[] json)
        throws InvalidJsonException {
        return parse(new InputStreamReader(new ByteArrayInputStream(json), StandardCharsets.UTF_8));
    }

    @Override
    public Object parse(InputStream jsonStream, String charset) throws InvalidJsonException {
        try {
            return parse(new InputStreamReader(jsonStream, charset));
        } catch (UnsupportedEncodingException e) {
            throw new JsonPathException(e);
        }
    }

  private Object parse(Reader jsonInput) {
    try (JsonReader jsonReader = defaultJsonProvider.createReader(jsonInput)) {
        JsonStructure jsonStruct = jsonReader.read();
        return mutableJson ? proxyAll(jsonStruct) : jsonStruct;
    } catch (JsonParsingException e) {
        throw new InvalidJsonException(e);
    }
    // not catching a JsonException as it never happens here
  }

    @Override
    public String toJson(Object obj) {
        if (obj instanceof JsonObjectBuilder) {
            obj = ((JsonObjectBuilder) obj).build();
        } else if (obj instanceof JsonArrayBuilder) {

View on GitHub (pinned to 62a4c9f0f6)

Solutions

Use StandardCharsets.UTF_8.name() (or another guaranteed standard charset) instead of free-form strings.
Validate charset names with Charset.isSupported(name) before calling parse.
Prefer the parse(String) or parse(byte[]) style APIs that avoid explicit charset handling.

Example fix

// before
Object doc = JsonPath.parse(stream, "utf-8");
// after
Object doc = JsonPath.parse(stream, StandardCharsets.UTF_8.name());

Defensive patterns

Strategy: validation

Validate before calling

// Java
if (!Charset.isSupported(charsetName)) throw new IllegalArgumentException("Unsupported charset: " + charsetName);

Try / catch

try { return JsonPath.parse(stream, charset); } catch (JsonPathException e) { throw new IllegalArgumentException("Bad charset", e); }

Prevention

Use StandardCharsets.*.name()
Never pass charset strings from unvalidated config/headers
Prefer parse(String) when the source is already decoded

When it happens

Trigger: Calling parse(InputStream, charset) with a charset name not supported by the JVM, e.g. a misspelled 'UTF8 '-' variant issue or an exotic charset on a minimal JRE.

Common situations: Hard-coded charset strings from config files, charsets coming from HTTP headers that are invalid, or running on a stripped JVM lacking optional charset providers.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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