hibernate/hibernate-orm · error · QueryException

Can't emulate on empty clause on CockroachDB

Error message

Can't emulate on empty clause on CockroachDB

What it means

Validation guard in the CockroachDB json_table emulation (renderJsonQueryColumnDefinition): a json_table query column declared an 'on empty' behavior other than ERROR/NULL default. Because the function is emulated with jsonb_path_query, whose behavior on empty results cannot be overridden in the generated CockroachDB SQL, the requested empty-behavior clause is unsupported and rendering throws. Drop the on-empty clause for this column.

Solutions

1. Remove the ON EMPTY clause for CockroachDB.

When it happens

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

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 on empty clause on CockroachDB.

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

Appendix: source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/function/json/CockroachDBJsonTableFunction.java:169

				sqlAppender,
				new ClauseLevelDocumentExpression( clauseLevel ),
				JsonPathHelper.parseJsonPathElements( jsonPath ),
				true,
				null,
				walker
		);
		sqlAppender.appendSql( ' ' );
		sqlAppender.appendSql( definition.name() );
	}

	@Override
	protected void renderJsonQueryColumnDefinition(SqlAppender sqlAppender, JsonTableQueryColumnDefinition definition, int clauseLevel, SqlAstTranslator<?> walker) {
		// jsonb_path_query functions error by default
		if ( definition.errorBehavior() != null && definition.errorBehavior() != JsonQueryErrorBehavior.ERROR ) {
			throw new QueryException( "Can't emulate on error clause on CockroachDB" );
		}
		if ( definition.emptyBehavior() != null && definition.emptyBehavior() != JsonQueryEmptyBehavior.NULL ) {
			throw new QueryException( "Can't emulate on empty clause on CockroachDB" );
		}
		final JsonQueryWrapMode wrapMode = definition.wrapMode();

		if ( wrapMode == JsonQueryWrapMode.WITH_WRAPPER ) {
			sqlAppender.appendSql( "jsonb_build_array(" );
		}
		final String jsonPath = definition.jsonPath() == null
				? "$." + definition.name()
				: definition.jsonPath();
		CockroachDBJsonQueryFunction.appendJsonQuery(
				sqlAppender,
				new ClauseLevelDocumentExpression( clauseLevel ),
				JsonPathHelper.parseJsonPathElements( jsonPath ),
				true,
				null,
				walker
		);
		if ( wrapMode == JsonQueryWrapMode.WITH_WRAPPER ) {

View on GitHub (pinned to fad1729dce)