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.

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)

Solutions

1. Build factories through the standard pipeline (Configuration.buildSessionFactory() or SessionFactoryBuilder) so the uuid is generated for you
2. If you construct SessionFactoryOptions yourself, always set a uuid (options.uuid(UUID.randomUUID().toString())) before addSessionFactory
3. Add an assertion in custom bootstrap code: Objects.requireNonNull(options.getUuid()) with a clear message
4. 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);

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

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 parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• #buildNamedQueryRepository should not be called on InFlightM
• You should not be building a SessionFactory from an in-fligh
• Bootstrap registry should only contain provided services
• Unable to find listeners for type [
• Unable to build Hibernate SessionFactory [persistence unit:

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