What causes "proxy class not found: " + proxyInterfaceName" in hibernate/hibernate-orm?

Fix the interface name in @Proxy(proxyInterface=...) or the hbm proxy element

hibernate/hibernate-orm · error · MappingException

proxy class not found: " + proxyInterfaceName

Error message

proxy class not found: " + proxyInterfaceName

What it means

Thrown when Hibernate cannot load the interface used to generate proxies for an entity. PersistentClass.getProxyInterface() resolves the proxyInterfaceName recorded from @Proxy(proxyInterface=...) or the proxy element in hbm.xml; a ClassLoadingException is wrapped in this MappingException. The mapping names a proxy interface that is not on the classpath (or has been renamed).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java:191

			return mappedClass;
		}
		catch (ClassLoadingException e) {
			throw new MappingException( "entity class not found: " + className, e );
		}
	}

	public Class<?> getProxyInterface() {
		if ( proxyInterfaceName == null ) {
			return null;
		}
		try {
			if ( proxyInterface == null ) {
				proxyInterface = getClassForName( proxyInterfaceName );
			}
			return proxyInterface;
		}
		catch (ClassLoadingException e) {
			throw new MappingException( "proxy class not found: " + proxyInterfaceName, e );
		}
	}

	public boolean useDynamicInsert() {
		return dynamicInsert;
	}

	abstract int nextSubclassId();

	public abstract int getSubclassId();

	public boolean useDynamicUpdate() {
		return dynamicUpdate;
	}

	public void setDynamicInsert(boolean dynamicInsert) {
		this.dynamicInsert = dynamicInsert;
	}

View on GitHub (pinned to fad1729dce)

Solutions

Fix the interface name in @Proxy(proxyInterface=...) or the hbm proxy element
Ship the artifact that contains the proxy interface with the deployment
Remove the @Proxy annotation if default proxying of the entity class itself is acceptable

Example fix

// before
@Entity
@Proxy(proxyInterface = OldUserApi.class)
public class User implements UserApi { ... }

// after
@Entity
@Proxy(proxyInterface = UserApi.class)
public class User implements UserApi { ... }

Defensive patterns

Strategy: validation

Validate before calling

for (PersistentClass pc : metadata.getEntityBindings()) {
    String proxy = pc.getProxyInterfaceName();
    if (proxy == null) continue;
    Class<?> iface = Class.forName(proxy, false, cl);
    if (!iface.isInterface()) {
        throw new IllegalArgumentException(proxy); // proxy target must be an interface
    }
}

Type guard

static boolean isLoadableInterface(String name, ClassLoader cl) {
    try {
        return Class.forName(name, false, cl).isInterface();
    }
    catch (ClassNotFoundException e) {
        return false;
    }
}

Prevention

Reference proxy interfaces by class literal (@Proxy(proxyInterface = UserApi.class)), never by string
Make proxy interfaces part of the same artifact as the entity or a guaranteed dependency
Drop @Proxy unless you actually need interface-based lazy proxies

When it happens

Trigger: An entity annotated @Proxy(proxyInterface = SomeApi.class) where SomeApi lives in a jar absent from the runtime classpath; an hbm proxy interface attribute holding a stale name after an interface rename; the referenced type exists but the mapping points at the implementing class rather than an interface.

Common situations: Splitting API and model into separate artifacts and forgetting the API jar on the server; refactors that renamed proxy interfaces without regenerating XML; copy-pasting proxy settings between entities.

Related errors

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