{"record":{"id":"d1643d0324ff226f","repo":"hibernate/hibernate-orm","slug":"typeconfiguration-was-not-yet-scoped-to-sessionfac","errorCode":null,"errorMessage":"TypeConfiguration was not yet scoped to SessionFactory","messagePattern":"TypeConfiguration was not yet scoped to SessionFactory","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java","lineNumber":561,"sourceCode":"\t\t\t\treturn metadataBuildingContext.getBootstrapContext().getJpaCompliance();\n\t\t\t}\n\t\t\telse if ( sessionFactory != null ) {\n\t\t\t\treturn sessionFactory.getSessionFactoryOptions().getJpaCompliance();\n\t\t\t}\n\t\t\treturn null;\n\t\t}\n\n\t\tprivate void setMetadataBuildingContext(MetadataBuildingContext context) {\n\t\t\tmetadataBuildingContext = context;\n\t\t\tif ( context != null ) {\n\t\t\t\tallowExtensionsInCdi = context.getBuildingOptions().isAllowExtensionsInCdi();\n\t\t\t}\n\t\t}\n\n\t\tprivate SessionFactoryImplementor getSessionFactory() {\n\t\t\tif ( sessionFactory == null ) {\n\t\t\t\tif ( sessionFactoryName == null && sessionFactoryUuid == null ) {\n\t\t\t\t\tthrow new HibernateException( \"TypeConfiguration was not yet scoped to SessionFactory\" );\n\t\t\t\t}\n\t\t\t\tsessionFactory =\n\t\t\t\t\t\tSessionFactoryRegistry.INSTANCE\n\t\t\t\t\t\t\t\t.findSessionFactory( sessionFactoryUuid, sessionFactoryName );\n\t\t\t\tif ( sessionFactory == null ) {\n\t\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\t\"Could not find a SessionFactory [uuid=\" + sessionFactoryUuid + \",name=\" + sessionFactoryName + \"]\"\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn sessionFactory;\n\t\t}\n\n\t\t/**\n\t\t * Used by {@link TypeConfiguration} scoping.\n\t\t *\n\t\t * @param factory The {@link SessionFactory} to which the {@link TypeConfiguration} is being bound\n\t\t */","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java#L543-L579","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Make sure Metadata.buildSessionFactory() has fully completed before any Session, query, or cache usage that resolves types","Do not cache Metadata, TypeConfiguration, or resolved Hibernate Types across SessionFactory builds or after close; rebuild them per factory","If this appears right after a failed bootstrap, fix the original build failure first - this error is often fallout from an aborted SessionFactory construction","Upgrade Hibernate - several TypeConfiguration-scoping bugs in this area (HHH issue tracker) were fixed in later 5.x/6.x patch releases"],"exampleFix":"// before - resolves during setParameterValues, before the factory is scoped\n@Override\npublic void setParameterValues(Properties parameters) {\n    // needs SessionFactory-scoped services: throws during metadata building\n    this.jdbcType = typeConfiguration.getJdbcTypeResolver().resolve(\n        JdbcTypeSqlCodes.CODE_BOOLEAN\n    );\n}\n\n// after - defer resolution until after scoping to the SessionFactory\n@Override\nprotected void resolve(BiConsumer<BasicJavaType<Object>, JdbcType> resolutionConsumer) {\n    // safe: runs once the TypeConfiguration is scoped to the factory\n    resolutionConsumer.accept(javaType, typeConfiguration.getJdbcTypeRegistry().getDescriptor(Types.BOOLEAN));\n}","handlingStrategy":"try-catch","validationCode":"// finish bootstrap before any type-dependent API is touched\nMetadata metadata = metadataSources.buildMetadata();\ntry (SessionFactory factory = metadata.buildSessionFactory()) {\n    // TypeConfiguration is now scoped to `factory` - safe to resolve types here\n    try (Session s = factory.openSession()) {\n        s.createSelectionQuery(\"from Order\", Order.class).getResultList();\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    session.createQuery(...);\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"TypeConfiguration was not yet scoped\")) {\n        // bootstrap-order bug: build/complete the SessionFactory first, then retry\n        throw new IllegalStateException(\"SessionFactory bootstrap incomplete\", e);\n    }\n    throw e;\n}","preventionTips":["Never cache Metadata, TypeConfiguration, or resolved Hibernate Types across SessionFactory builds or after close","Defer type resolution in custom types until after bootstrap instead of doing it in constructors or setParameterValues","Build the SessionFactory once at application start, before any thread opens sessions or runs queries","In tests, rebuild bootstrap state per factory instead of reusing statics"],"tags":["hibernate","orm","bootstrap","type-configuration","session-factory"],"backgroundTag":"hibernate-typeconfiguration-not-scoped","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}