hibernate/hibernate-orm · error · HibernateException

Type to register cannot be null

Error message

Type to register cannot be null

What it means

BasicTypeRegistry.register(BasicType<?>, String...) (BasicTypeRegistry.java:375-385) guards its first argument and throws HibernateException 'Type to register cannot be null' when null is passed. The registry is populated at bootstrapping and extended through TypeContributor SPIs or MetadataBuilder type contributions, so this error means some contribution path handed null into register - usually a lookup or factory step that returned null upstream.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/BasicTypeRegistry.java:381

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Mutations

	public void register(BasicType<?> type) {
		register( type, type.getRegistrationKeys() );
	}

	public void register(BasicType<?> type, String key) {
		register( type, new String[]{ key } );
	}

	public void register(BasicType<?> type, String... keys) {
		if ( ! isPrimed() ) {
			throw new IllegalStateException( "BasicTypeRegistry not yet primed. Calls to `#register` not valid until after primed" );
		}

		if ( type == null ) {
			throw new HibernateException( "Type to register cannot be null" );
		}

		// explicit registration keys
		if ( isEmpty( keys ) ) {
			CORE_LOGGER.typeDefinedNoRegistrationKeys( type );
		}
		else {
			applyRegistrationKeys( type, keys );
		}
	}

	public <T> CustomType<T> register(UserType<T> type, String... keys) {
		final var customType = new CustomType<>( type, keys, typeConfiguration );
		register( customType );
		return customType;
	}

	public void unregister(String... keys) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the BasicType instance is constructed before contributing it; never pass a possibly-null value into contributeBasicType/register.
2. If the type is optional, guard the contribution with an existence check and contribute nothing when unavailable.
3. If you depended on another contributor's type, look it up after bootstrap (Metadata.getDatabase/TypeConfiguration) instead of expecting it during contribution.
4. Add a unit test that runs your TypeContributor against a StandardServiceRegistry to catch null contributions at build time.

Example fix

// before
public class MyTypeContributor implements TypeContributor {
    public void contribute(TypeContributions c, ServiceRegistry r) {
        c.contributeBasicType(findType()); // findType() may return null
    }
}

// after
public class MyTypeContributor implements TypeContributor {
    public void contribute(TypeContributions c, ServiceRegistry r) {
        BasicType<?> t = findType();
        if (t != null) {
            c.contributeBasicType(t);
        }
    }
}

public void contribute(TypeContributions c, ServiceRegistry r) {
    BasicType<?> type = resolveType(); // may fail
    if (type == null) {
        return; // contribute nothing rather than null
    }
    c.contributeBasicType(type);
}

static boolean isRegisterable(BasicType<?> t) {
    return t != null;
}

try {
    registry.register(type, keys);
} catch (HibernateException e) {
    if ("Type to register cannot be null".equals(e.getMessage())) {
        log.warn("Skipping null basic type for keys {}", (Object[]) keys);
        return;
    }
    throw e;
}

When it happens

Trigger: A custom org.hibernate.boot.model.TypeContributor calling typeContributions.contributeBasicType(null) or register(null, "mykey"); MetadataBuilder.applyBasicType(null); programmatic BasicTypeRegistry.register(null, ...) after the registry is primed; a type produced conditionally (e.g. only when a dialect feature exists) being contributed unconditionally.

Common situations: Optional integrations that contribute a type only if an optional dependency is present and pass null otherwise; copy-pasted TypeContributor code where the constructor of the type throws or the field is not initialized; ordering issues where a contributor depends on another contributor having registered a type first.

Related errors

• The {storageEngine} storage engine is not supported
• The specified package name cannot be null
• Unknown type of binding : <bindingRoot>
• Unable to resolve <jar-file/> reference - {}
• Error activating Bean Validation integration

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