json-path/JsonPath · error · AssertionError

JSON path [%s] doesn't match. Expected: %s Actual: %s

Error message

JSON path [%s] doesn't match.
Expected:
%s
Actual:
%s

What it means

JsonAsserter.assertThat(path, matcher) reads the value at the given JSON path and applies a Hamcrest matcher. When the matcher does not match the value actually found, an AssertionError is thrown showing the matcher description as 'Expected' and the actual value. This is the core assertion failure of the json-path-assert (JsonAssert) fluent test API, not an exception from parsing.

Source

Thrown at json-path-assert/src/main/java/com/jayway/jsonassert/impl/JsonAsserterImpl.java:43

    /**
     * {@inheritDoc}
     */
    @SuppressWarnings("unchecked")
    public <T> JsonAsserter assertThat(String path, Matcher<T> matcher) {
        T obj = null;
        
        try {
            obj = JsonPath.<T>read(jsonObject, path);
        } catch (Exception e) {
            final AssertionError assertionError = new AssertionError(String.format("Error reading JSON path [%s]", path));
            assertionError.initCause(e);
            throw assertionError;
        }

        if (!matcher.matches(obj)) {

            throw new AssertionError(String.format("JSON path [%s] doesn't match.\nExpected:\n%s\nActual:\n%s", path, matcher.toString(), obj));
        }
        return this;
    }

    /**
     * {@inheritDoc}
     */
    @SuppressWarnings("unchecked")
    public <T> JsonAsserter assertThat(String path, Matcher<T> matcher, String message) {
        T obj = JsonPath.<T>read(jsonObject, path);
        if (!matcher.matches(obj)) {
            throw new AssertionError(String.format("JSON Assert Error: %s\nExpected:\n%s\nActual:\n%s", message, matcher.toString(), obj));
        }
        return this;
    }

    /**
     * {@inheritDoc}

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Print the actual document and compare with matcher.toString() output shown in the AssertionError to see the exact divergence.
2. Verify the JSON path with JsonPath.read() standalone to confirm which node it selects.
3. Fix the expected value/matcher, or fix the path if it selects the wrong node.
4. If the value legitimately varies, use a more tolerant matcher (e.g. hasItem, containsString, anyOf).

Example fix

// before
with(response).assertThat("$.user.name", equalTo("alice"));
// after
with(response).assertThat("$.user.name", anyOf(equalTo("alice"), equalTo("Alice")));

Object actual = JsonPath.read(json, path);
if (!matcher.matches(actual)) throw new AssertionError("pre-check failed for " + path + ": " + actual);

try {
    with(json).assertThat(path, matcher);
} catch (AssertionError e) {
    log.warn("JSON assertion failed: {}", e.getMessage());
    throw e; // rethrow — assertion failures should fail the test
}

When it happens

Trigger: Calling JsonAssert.with(json).assertThat("$.field", Matchers.equalTo(expected)) where the value at the path exists but differs from what the matcher requires; also any matcher mismatch (empty-ness, size, type comparisons) via the assertThat overloads used by assertEquals/assertNull/assertNotNull.

Common situations: Unit/integration tests asserting JSON response bodies where the API output changed (new field value, different casing, number vs string), or where the JSON path selects the wrong node (e.g. missing '.[0]' on an array).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• JSON Assert Error: %s Expected: %s Actual: %s
• Document contains the path <%s> but was expected not to.
• e
• Could not convert
• InvalidJsonException

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