What causes "Can't emulate non-simple json path expression: {jsonPath}" in hibernate/hibernate-orm?

Rewrite the path with explicit simple segments: replace '$.items[*]' with a set-based query over json_table.

hibernate/hibernate-orm · error · QueryException

Can't emulate non-simple json path expression: {jsonPath}

Error message

Can't emulate non-simple json path expression: {jsonPath}

What it means

The emulation parses only simple path segments: attributes joined by dots and bracket indexes. parseAttribute and parseBracket throw on wildcards, ranges like [1 to 3], filter expressions like ?(@.x), or non-numeric bracket content. The catch block wraps any such failure in this QueryException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/function/json/JsonPathHelper.java:47

				startIndex = 2;
			}
			else {
				final int bracketEndIndex = jsonPath.indexOf( ']' );
				parseBracket( jsonPath, 1, bracketEndIndex, jsonPathElements );
				startIndex = bracketEndIndex + 2;
			}

			try {
				while ( ( dotIndex = jsonPath.indexOf( '.', startIndex ) ) != -1 ) {
					parseAttribute( jsonPath, startIndex, dotIndex, jsonPathElements );
					startIndex = dotIndex + 1;
				}
				if ( startIndex < jsonPath.length() ) {
					parseAttribute( jsonPath, startIndex, jsonPath.length(), jsonPathElements );
				}
			}
			catch (Exception ex) {
				throw new QueryException( "Can't emulate non-simple json path expression: " + jsonPath, ex );
			}
		}
		return jsonPathElements;
	}

	public static void appendJsonPathConcatPassingClause(
			SqlAppender sqlAppender,
			Expression jsonPathExpression,
			JsonPathPassingClause passingClause, SqlAstTranslator<?> walker) {
		appendJsonPathConcatenatedPassingClause( sqlAppender, jsonPathExpression, passingClause, walker, "concat", "," );
	}

	public static void appendJsonPathDoublePipePassingClause(
			SqlAppender sqlAppender,
			Expression jsonPathExpression,
			JsonPathPassingClause passingClause,
			SqlAstTranslator<?> walker) {
		appendJsonPathConcatenatedPassingClause( sqlAppender, jsonPathExpression, passingClause, walker, "", "||" );

View on GitHub (pinned to fad1729dce)

Solutions

Rewrite the path with explicit simple segments: replace '$.items[*]' with a set-based query over json_table.
Move filtering and slicing into HQL/SQL predicates instead of the path expression.
Use a native query for statements that need wildcards, ranges, or filter expressions.
Keep paths to the supported forms: '$.attr.attr2' and '$.attr[0]' (plus [$param] with a passing clause).

Example fix

// before
select json_query(e.doc, '$.items[*].name') from Entity e

// after
select t.name from Entity e, json_table(e.doc, '$.items' columns(name varchar path '$.name')) t

Defensive patterns

Strategy: validation

Validate before calling

// Only simple segments survive emulation: $, .attr, [n], [$name].
static final java.util.regex.Pattern SIMPLE =
    java.util.regex.Pattern.compile("^\\$(\\.[A-Za-z_][\\w]*(\\[\\d+]|\\[\\$\\w+])?)*$");

static boolean isEmulatablePath(String path) {
    return SIMPLE.matcher(path).matches();
}

if (!isEmulatablePath(path)) {
    throw new UnsupportedOperationException("JSON path needs native dialect support: " + path);
}

Type guard

static boolean isSimpleJsonPath(String path) {
    return path != null && java.util.regex.Pattern
        .compile("^\\$(\\.[A-Za-z_][\\w]*(\\[\\d+]|\\[\\$\\w+])?)*$")
        .matcher(path).matches();
}

Try / catch

try {
    return session.createQuery(hql, String.class).getSingleResult();
} catch (org.hibernate.QueryException e) {
    if (e.getMessage() != null && e.getMessage().contains("non-simple json path")) {
        // Split the query: use json_table + predicates instead of an advanced path.
        throw new UnsupportedOperationException("Rewrite the path with json_table or run native SQL", e);
    }
    throw e;
}

Prevention

Restrict path constants to '$.attr' and '[n]' forms for portable HQL.
Express wildcards and slices with json_table plus WHERE predicates.
Add a lint check for advanced path syntax in query constants.

When it happens

Trigger: A query passes a path with advanced SQL/JSON syntax, for example '$.items[*]', '$.items[1 to 3]', or '$.items?(@.price > 10)', on a dialect that uses path emulation.

Common situations: Paths validated against PostgreSQL or Oracle behavior, where richer path grammar is native. Business requirements that ask for array slices and filters inside the path.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/91ff231a371d0f68. Report an issue: GitHub.