json-path/JsonPath · error · AssertionError

JSON Assert Error: %s Expected: %s Actual: %s

Error message

JSON Assert Error: %s
Expected:
%s
Actual:
%s

What it means

The message-taking overload of JsonAsserter.assertThat behaves like the plain overload: it reads the path and applies the matcher, throwing AssertionError with the caller-supplied message plus matcher and actual value when the matcher fails. The custom message is purely descriptive context; the root cause is a matcher mismatch.

Source

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

            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}
     */
    public <T> JsonAsserter assertEquals(String path, T expected) {
        return assertThat(path, equalTo(expected));
    }

    /**
     * {@inheritDoc}
     */
    public JsonAsserter assertNotDefined(String path) {

        try {
            Configuration c = Configuration.defaultConfiguration();

View on GitHub (pinned to 62a4c9f0f6)

Solutions

  1. Read the 'Expected'/'Actual' sections of the AssertionError to identify the mismatch.
  2. Re-run JsonPath.read on the path to inspect the live value.
  3. Update the matcher/expected value or the JSON fixture to the correct state.
  4. Adjust the custom message if it no longer accurately describes the assertion.

Example fix

// before
with(json).assertThat("$.count", equalTo(2), "count must be 2");
// after
int actual = JsonPath.read(json, "$.count");
with(json).assertThat("$.count", equalTo(actual), "count must match fixture");
Defensive patterns

Strategy: validation

Validate before calling

T actual = JsonPath.<T>read(jsonObject, path);
if (!matcher.matches(actual)) throw new AssertionError(message + " | actual=" + actual);

Try / catch

try {
    with(json).assertThat(path, matcher, message);
} catch (AssertionError e) {
    log.error("JSON assert failed: {}", e.getMessage());
    throw e;
}

Prevention

When it happens

Trigger: JsonAssert.with(json).assertThat("$.items.size()", hasSize(3), "expected 3 items") — any call where matcher.matches(obj) returns false, with the message parameter supplied.

Common situations: Test suites that add business-readable messages to JSON assertions, then fail after an upstream API or fixture changes; commonly seen when asserting computed values like .length() or .size().

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

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