hibernate/hibernate-orm · error · QueryException

Can't emulate wrapper clause on MySQL

Error message

Can't emulate wrapper clause on MySQL

What it means

Error "Can't emulate wrapper clause on MySQL" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/function/json/MySQLJsonTableFunction.java:125

			if ( definition.emptyBehavior() == JsonValueEmptyBehavior.ERROR ) {
				sqlAppender.appendSql( " error on empty" );
			}
			else if ( definition.emptyBehavior() != JsonValueEmptyBehavior.NULL ) {
				final Expression defaultExpression = definition.emptyBehavior().getDefaultExpression();
				assert defaultExpression != null;
				sqlAppender.appendSql( " default " );
				defaultExpression.accept( walker );
				sqlAppender.appendSql( " on empty" );
			}
		}
		// todo: mismatch clause?
	}

	@Override
	protected void renderJsonQueryColumnDefinition(SqlAppender sqlAppender, JsonTableQueryColumnDefinition definition, int clauseLevel, SqlAstTranslator<?> walker) {
		// Conditional wrapper is the default behavior on MySQL
		if ( definition.wrapMode() != null && definition.wrapMode() != JsonQueryWrapMode.WITH_CONDITIONAL_WRAPPER ) {
			throw new QueryException( "Can't emulate wrapper clause on MySQL" );
		}
		sqlAppender.appendSql( definition.name() );
		sqlAppender.appendSql( ' ' );
		sqlAppender.appendSql( DdlTypeHelper.getTypeName( definition.type(),
				walker.getSessionFactory().getTypeConfiguration() ) );
		if ( definition.type().getJdbcType().getDdlTypeCode() != SqlTypes.JSON ) {
			sqlAppender.appendSql( " format json" );
		}

		if ( definition.jsonPath() != null ) {
			sqlAppender.appendSql( " path " );
			sqlAppender.appendSingleQuoteEscapedString( definition.jsonPath() );
		}
		else {
			sqlAppender.appendSql( " path '$." );
			sqlAppender.appendSql( definition.name() );
			sqlAppender.appendSql( "'" );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the WITH WRAPPER clause for MySQL.

When it happens

Trigger: Triggered when the application calls a Hibernate dialect feature that the configured database dialect cannot provide: Can't emulate wrapper clause on MySQL.

Common situations: Common when running against a database whose dialect lacks this capability, when a mapping or HQL/Criteria query requests unsupported functionality, or when the wrong dialect is configured for the database in use. Error: Can't emulate wrapper clause on MySQL.

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