hibernate/hibernate-orm · error · HibernateException

TypeConfiguration was not yet scoped to SessionFactory

Error message

TypeConfiguration was not yet scoped to SessionFactory

What it means

Hibernate binds each TypeConfiguration to a SessionFactory during bootstrap: first to the MetadataBuildingContext while mappings are processed, then to the factory when Metadata.buildSessionFactory() runs. This HibernateException is thrown from TypeConfiguration.Scope#getSessionFactory when code asks for the factory before that second scoping happened - the scope holds neither a factory instance nor a name/UUID. It means a type or service needed SessionFactory-level state during the metadata-building phase, or after the owning factory was closed/unbound.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java:561

				return metadataBuildingContext.getBootstrapContext().getJpaCompliance();
			}
			else if ( sessionFactory != null ) {
				return sessionFactory.getSessionFactoryOptions().getJpaCompliance();
			}
			return null;
		}

		private void setMetadataBuildingContext(MetadataBuildingContext context) {
			metadataBuildingContext = context;
			if ( context != null ) {
				allowExtensionsInCdi = context.getBuildingOptions().isAllowExtensionsInCdi();
			}
		}

		private SessionFactoryImplementor getSessionFactory() {
			if ( sessionFactory == null ) {
				if ( sessionFactoryName == null && sessionFactoryUuid == null ) {
					throw new HibernateException( "TypeConfiguration was not yet scoped to SessionFactory" );
				}
				sessionFactory =
						SessionFactoryRegistry.INSTANCE
								.findSessionFactory( sessionFactoryUuid, sessionFactoryName );
				if ( sessionFactory == null ) {
					throw new HibernateException(
							"Could not find a SessionFactory [uuid=" + sessionFactoryUuid + ",name=" + sessionFactoryName + "]"
					);
				}
			}
			return sessionFactory;
		}

		/**
		 * Used by {@link TypeConfiguration} scoping.
		 *
		 * @param factory The {@link SessionFactory} to which the {@link TypeConfiguration} is being bound
		 */

View on GitHub (pinned to fad1729dce)

Solutions

1. Defer type resolution until after the factory exists: in custom types move resolution out of constructors/setParameterValues into lazy resolution (e.g. override resolve(...) on UserTypeLegacyBridge-style types)
2. Make sure Metadata.buildSessionFactory() has fully completed before any Session, query, or cache usage that resolves types
3. Do not cache Metadata, TypeConfiguration, or resolved Hibernate Types across SessionFactory builds or after close; rebuild them per factory
4. If this appears right after a failed bootstrap, fix the original build failure first - this error is often fallout from an aborted SessionFactory construction
5. Upgrade Hibernate - several TypeConfiguration-scoping bugs in this area (HHH issue tracker) were fixed in later 5.x/6.x patch releases

Example fix

// before - resolves during setParameterValues, before the factory is scoped
@Override
public void setParameterValues(Properties parameters) {
    // needs SessionFactory-scoped services: throws during metadata building
    this.jdbcType = typeConfiguration.getJdbcTypeResolver().resolve(
        JdbcTypeSqlCodes.CODE_BOOLEAN
    );
}

// after - defer resolution until after scoping to the SessionFactory
@Override
protected void resolve(BiConsumer<BasicJavaType<Object>, JdbcType> resolutionConsumer) {
    // safe: runs once the TypeConfiguration is scoped to the factory
    resolutionConsumer.accept(javaType, typeConfiguration.getJdbcTypeRegistry().getDescriptor(Types.BOOLEAN));
}

// finish bootstrap before any type-dependent API is touched
Metadata metadata = metadataSources.buildMetadata();
try (SessionFactory factory = metadata.buildSessionFactory()) {
    // TypeConfiguration is now scoped to `factory` - safe to resolve types here
    try (Session s = factory.openSession()) {
        s.createSelectionQuery("from Order", Order.class).getResultList();
    }
}

try {
    session.createQuery(...);
} catch (HibernateException e) {
    if (e.getMessage() != null && e.getMessage().contains("TypeConfiguration was not yet scoped")) {
        // bootstrap-order bug: build/complete the SessionFactory first, then retry
        throw new IllegalStateException("SessionFactory bootstrap incomplete", e);
    }
    throw e;
}

When it happens

Trigger: A BasicType, UserType, or converter that calls typeConfiguration.getSessionFactory() (directly or via JdbcType/JavaType resolution) during setParameterValues or construction instead of after scoping; opening a Session or executing a query while bootstrap is still in the metadata phase; cleanup/rollback code touching types after sessionFactory.close() removed the scoping; reusing a stale TypeConfiguration or Metadata from a previous factory lifecycle.

Common situations: Custom UserType implementations doing eager type resolution at bootstrap; tests that cache Metadata or Hibernate Types in static fields but rebuild the SessionFactory per test; a partially failed SessionFactory build leaving half-initialized types that later code touches; upgrading to Hibernate 5.3+/6.x where TypeConfiguration scoping became strict.

Related errors

• TypeConfiguration is not currently scoped to MetadataBuildin
• You should not be building a SessionFactory from an in-fligh
• Named query definition is null
• Named query definition name is null: %s
• Duplicate named query '%s'

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