hibernate/hibernate-orm · error · JdbcTypeRecommendationException

Could not determine recommended JdbcType for `" + getTypeNam

Error message

Could not determine recommended JdbcType for `" + getTypeName() + "`"

What it means

EmbeddableAggregateJavaType backs embeddables stored as one aggregate column (JSON or SQL/XML). getRecommendedJdbcType() looks up the dialect's SQLXML or JSON JdbcType; when the dialect registers neither, no column type can be suggested and bootstrap fails with JdbcTypeRecommendationException naming the embeddable's Java type.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/EmbeddableAggregateJavaType.java:65

		}
		// When the column is mapped as XML array, the component type must be SQLXML
		final Integer explicitJdbcTypeCode = context.getExplicitJdbcTypeCode();
		if ( explicitJdbcTypeCode != null && explicitJdbcTypeCode == SqlTypes.XML_ARRAY
				// Also prefer XML if the Dialect prefers XML arrays
				|| explicitJdbcTypeCode == null && context.getDialect().getPreferredSqlTypeCodeForArray() == SqlTypes.XML_ARRAY ) {
			final var descriptor = context.getJdbcType( SqlTypes.SQLXML );
			if ( descriptor != null ) {
				return descriptor;
			}
		}
		else {
			// Otherwise use json by default for now
			final var descriptor = context.getJdbcType( SqlTypes.JSON );
			if ( descriptor != null ) {
				return descriptor;
			}
		}
		throw new JdbcTypeRecommendationException(
				"Could not determine recommended JdbcType for `" + getTypeName() + "`"
		);
	}

	@Override
	public <X> X unwrap(T value, Class<X> type, WrapperOptions options) {
		if ( type.isAssignableFrom( getJavaTypeClass() ) ) {
			return type.cast( value );
		}
		throw new UnsupportedOperationException(
				"Unwrap strategy not known for this Java type: " + getTypeName()
		);
	}

	@Override
	public <X> T wrap(X value, WrapperOptions options) {
		if ( value == null ) {
			return null;

View on GitHub (pinned to fad1729dce)

Solutions

  1. Switch to a dialect with native JSON support (PostgreSQL, H2 2.x+, MariaDB 10.5+/MySQL 8, SQL Server) or upgrade the hibernate-community-dialects artifact
  2. Register a JSON JdbcType from a TypeContributor: typeConfiguration.getJdbcTypeRegistry().addDescriptorIfAbsent(jsonJdbcType)
  3. Fall back to SqlTypes.LONG_STRING plus an AttributeConverter that serializes the embeddable manually
  4. Upgrade the database/engine itself to a version with JSON or XML support

Example fix

// before: aggregate embeddable on a dialect without JSON JDBC type
@Embeddable class Address { String city; }
@Entity class Customer {
    @Embedded @JdbcTypeCode(SqlTypes.JSON)
    Address address; // boot fails: no JSON/SQLXML descriptor registered
}

// after: use a JSON-capable dialect
// spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
@Embeddable class Address { String city; }
@Entity class Customer {
    @Embedded @JdbcTypeCode(SqlTypes.JSON)
    Address address;
}
Defensive patterns

Strategy: validation

Validate before calling

// fail fast at boot when the dialect cannot host JSON/XML aggregates
org.hibernate.type.descriptor.java.spi.JdbcTypeRegistry jdbcTypes =
    typeConfiguration.getJdbcTypeRegistry();
if (jdbcTypes.getDescriptor(org.hibernate.type.SqlTypes.JSON) == null
        && jdbcTypes.getDescriptor(org.hibernate.type.SqlTypes.SQLXML) == null) {
    throw new IllegalStateException(
        "Dialect has no JSON/SQLXML JdbcType: cannot map aggregate embeddables");
}

Try / catch

try {
    metadata.buildSessionFactory();
} catch (org.hibernate.type.descriptor.java.spi.JdbcTypeRecommendationException e) {
    // switch to a JSON-capable dialect or register a JsonJdbcType via TypeContributor, then retry
}

Prevention

When it happens

Trigger: Mapping an @Embedded/@Embeddable aggregate (@JdbcTypeCode(SqlTypes.JSON) or SqlTypes.SQLXML) while running on a dialect with no JSON/SQLXML JdbcType — legacy or community dialects, old H2/HSQLDB/Derby versions, or a custom Dialect that never registers JSON support; also enabling the mapping before the JSON TypeContributor runs.

Common situations: Switching databases while keeping JSON-mapped embeddables; test suites running on an embedded database that lacks JSON; upgrading Hibernate where dialect JSON support moved or requires hibernate-community-dialects.

Related errors

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