mybatis/mybatis-3 · error · IllegalStateException

Cannot enable lazy loading because Javassist is not availabl

Error message

Cannot enable lazy loading because Javassist is not available. Add Javassist to your classpath.

What it means

JavassistProxyFactory's constructor verifies javassist.util.proxy.ProxyFactory is loadable; if the Javassist jar is not on the classpath it throws IllegalStateException. Javassist ships as an optional dependency of MyBatis and is the default proxy factory used for lazy loading since 3.5.10 (and the only supported one going forward).

Source

Thrown at src/main/java/org/apache/ibatis/executor/loader/javassist/JavassistProxyFactory.java:55

import org.apache.ibatis.reflection.ExceptionUtil;
import org.apache.ibatis.reflection.factory.ObjectFactory;
import org.apache.ibatis.reflection.property.PropertyCopier;
import org.apache.ibatis.reflection.property.PropertyNamer;
import org.apache.ibatis.session.Configuration;

/**
 * @author Eduardo Macarron
 */
public class JavassistProxyFactory implements org.apache.ibatis.executor.loader.ProxyFactory {

  private static final String FINALIZE_METHOD = "finalize";
  private static final String WRITE_REPLACE_METHOD = "writeReplace";

  public JavassistProxyFactory() {
    try {
      Resources.classForName("javassist.util.proxy.ProxyFactory");
    } catch (Throwable e) {
      throw new IllegalStateException(
          "Cannot enable lazy loading because Javassist is not available. Add Javassist to your classpath.", e);
    }
  }

  @Override
  public Object createProxy(Object target, ResultLoaderMap lazyLoader, Configuration configuration,
      ObjectFactory objectFactory, List<Class<?>> constructorArgTypes, List<Object> constructorArgs) {
    return EnhancedResultObjectProxyImpl.createProxy(target, lazyLoader, configuration, objectFactory,
        constructorArgTypes, constructorArgs);
  }

  public Object createDeserializationProxy(Object target, Map<String, ResultLoaderMap.LoadPair> unloadedProperties,
      ObjectFactory objectFactory, List<Class<?>> constructorArgTypes, List<Object> constructorArgs) {
    return EnhancedDeserializationProxyImpl.createProxy(target, unloadedProperties, objectFactory, constructorArgTypes,
        constructorArgs);
  }

  static Object createStaticProxy(Class<?> type, MethodHandler callback, List<Class<?>> constructorArgTypes,

View on GitHub (pinned to 008069adb1)

Solutions

1. Add org.javassist:javassist to the runtime classpath (align with the version MyBatis's pom marks optional)
2. Verify with a dependency tree that no exclusion removed javassist transitively
3. Alternatively disable lazy loading (lazyLoadingEnabled=false) if eager fetching is acceptable — then no proxy factory is needed

Example fix

<!-- before: mybatis alone, javassist pruned -->
<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>3.5.x</version>
  <exclusions><exclusion><groupId>org.javassist</groupId><artifactId>javassist</artifactId></exclusion></exclusions>
</dependency>
<!-- after -->
<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>3.5.x</version>
</dependency>
<dependency>
  <groupId>org.javassist</groupId>
  <artifactId>javassist</artifactId>
  <version>3.29.0-GA</version>
</dependency>

try { Class.forName("javassist.util.proxy.ProxyFactory"); } catch (ClassNotFoundException e) { throw new IllegalStateException("javassist missing: lazy loading unavailable", e); }

static boolean javassistAvailable() { try { Class.forName("javassist.util.proxy.ProxyFactory"); return true; } catch (ClassNotFoundException e) { return false; } }

try { sqlSessionFactory.getConfiguration().setProxyFactory(new JavassistProxyFactory()); } catch (IllegalStateException e) { throw new IllegalStateException("Add org.javassist:javassist to the runtime classpath", e); }

When it happens

Trigger: Instantiating JavassistProxyFactory (the default when lazyLoadingEnabled=true, or explicitly via configuration.setProxyFactory) in a deployment where org.javassist:javassist is missing — slimmed-down classpaths, some OSGi containers, exclusion of transitive optional dependencies.

Common situations: Maven/Gradle excluding optional dependencies; fat-jar shading that drops optional jars; running only mybatis.jar without its optional proxies; deploying on containers that prune 'provided/optional' scopes.

Related errors

• Cannot enable lazy loading because CGLIB is not available. A
• Error creating lazy proxy. Cause: " + e
• Error setting driver on UnpooledDataSource.
• Cannot lazy load property [" + this.property + "] of deseria
• Cannot get Configuration as configuration factory was not se

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/1901fcda2aefbf03. Report an issue: GitHub.