What causes "SessionFactory UUID cannot be null" in hibernate/hibernate-orm?

Build factories through the standard pipeline (Configuration.buildSessionFactory() or SessionFactoryBuilder) so the uuid is generated for you

hibernate/hibernate-orm · error · IllegalArgumentException

SessionFactory UUID cannot be null

Error message

SessionFactory UUID cannot be null

What it means

SessionFactoryRegistry.addSessionFactory keys factories by uuid and treats null as a programmer error: IllegalArgumentException is thrown before any registration. In normal bootstrap the uuid comes from SessionFactoryOptions and is generated automatically, so hitting this means custom bootstrap code constructed or registered a factory implementation without a uuid.

Solutions

Build factories through the standard pipeline (Configuration.buildSessionFactory() or SessionFactoryBuilder) so the uuid is generated for you
If you construct SessionFactoryOptions yourself, always set a uuid (options.uuid(UUID.randomUUID().toString())) before addSessionFactory
Add an assertion in custom bootstrap code: Objects.requireNonNull(options.getUuid()) with a clear message
For wrapper factories, delegate to the wrapped factory's uuid instead of inventing a null one

Example fix

// before
SessionFactoryRegistry.INSTANCE.addSessionFactory(null, "myFactory", null, myFactoryImpl, null);
// IllegalArgumentException

// after
String uuid = myFactoryImpl.getUuid() != null
        ? myFactoryImpl.getUuid()
        : UUID.randomUUID().toString();
SessionFactoryRegistry.INSTANCE.addSessionFactory(uuid, "myFactory", null, myFactoryImpl, null);

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(uuid, "SessionFactory UUID cannot be null — "
        + "generate one via SessionFactoryBuilder or UUID.randomUUID()");
SessionFactoryRegistry.INSTANCE.addSessionFactory(uuid, name, jndiName, instance, jndiService);

Prevention

Use the standard Configuration/SessionFactoryBuilder pipeline so the uuid is auto-assigned
In custom bootstrap code, assert options.getUuid() is non-null with a descriptive message
Wrapper factory implementations should reuse the wrapped factory's uuid, not pass null

When it happens

Trigger: Calling SessionFactoryRegistry.INSTANCE.addSessionFactory(null, ...) from a custom SessionFactoryImplementor or custom bootstrap path; tests/fakes that register stand-in factories; code building SessionFactoryOptions manually and leaving the uuid unset.

Common situations: Custom SessionFactoryImplementor implementations (rare, e.g. wrappers/proxies passed to the registry); test harnesses that fake the registry; framework integrations that bypass the standard MetadataBuilder/SessionFactoryBuilder pipeline.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryRegistry.java:83

	}

	/**
	 * Adds a SessionFactory to the registry
	 *
	 * @param uuid The uuid under which to register the SessionFactory
	 * @param name The optional name under which to register the SessionFactory
	 * @param jndiName An optional name to use for binding the SessionFactory into JNDI
	 * @param instance The SessionFactory instance
	 * @param jndiService The JNDI service, so we can register a listener if name is a JNDI name
	 */
	public void addSessionFactory(
			String uuid,
			String name,
			String jndiName,
			SessionFactoryImplementor instance,
			JndiService jndiService) {
		if ( uuid == null ) {
			throw new IllegalArgumentException( "SessionFactory UUID cannot be null" );
		}

		REGISTRY_LOGGER.registeringSessionFactory( uuid, name == null ? "<unnamed>" : name );
		sessionFactoryMap.put( uuid, instance );
		if ( name != null ) {
			nameUuidXref.put( name, uuid );
		}

		if ( jndiName == null ) {
			REGISTRY_LOGGER.notBindingSessionFactory();
			return;
		}

		bindToJndi( jndiName, instance, jndiService );
	}

	private void bindToJndi(String jndiName, SessionFactoryImplementor instance, JndiService jndiService) {
		try {

View on GitHub (pinned to fad1729dce)