What causes "Created Sql Cache [${sqlCacheClass}] Error" in pagehelper-org/Mybatis-PageHelper?

Check the cause (PageException.getCause()) for the real error and fix it.

pagehelper-org/Mybatis-PageHelper · error · PageException

Created Sql Cache [ ] Error

Error message

Created Sql Cache [${sqlCacheClass}] Error

What it means

CacheFactory.createCache instantiates the configured sqlCacheClass (e.g. an EhCache or Redis SqlCache implementation). If loading/creating the cache instance throws for any reason (class missing, constructor failure, initialization error), the Throwable is wrapped in a PageException with this message and the original as cause.

Solutions

Check the cause (PageException.getCause()) for the real error and fix it.
Add the missing cache implementation dependency (e.g. com.github.pagehelper:pagehelper-sqlcache or ehcache/redis client jars).
Verify the sqlCacheClass value is the exact fully-qualified class name.
Validate the cache's own configuration (ehcache.xml / redis connection) loads correctly.

Example fix

// before (pom.xml missing dependency, config: sqlCacheClass=com.github.pagehelper.cache.EhCache)
// after
<dependency>
  <groupId>com.github.pagehelper</groupId>
  <artifactId>pagehelper-sqlcache</artifactId>
  <version>1.0.0</version>
</dependency>

Defensive patterns

Strategy: try-catch

Validate before calling

String cls = properties.getProperty("sqlCacheClass");
if (cls != null) {
    try { Class.forName(cls); } catch (ClassNotFoundException e) {
        throw new IllegalStateException("sqlCacheClass not on classpath: " + cls, e);
    }
}

Try / catch

try {
    interceptor.setProperties(props);
} catch (PageException e) {
    if (e.getCause() != null) log.error("sql cache init root cause", e.getCause());
    throw e;
}

Prevention

Read PageException.getCause() first — it carries the real cache instantiation error.
Confirm the cache dependency jar (pagehelper-sqlcache / ehcache / redis client) is in the final artifact.
Validate ehcache.xml or redis connection config in a startup smoke test.
Pin PageHelper and cache-module versions together.

When it happens

Trigger: Setting the sqlCacheClass plugin property to a class that does not exist on the classpath, cannot be instantiated (no no-arg constructor), or whose setProperties/init throws during PageHelper plugin initialization.

Common situations: Using pagehelper-sqlcache (EhCache/Redis) without adding the dependency jar; typo in the fully-qualified class name; cache library config file (ehcache.xml) missing or invalid so the cache constructor fails at startup.

Related errors

AI-assisted analysis of pagehelper-org/Mybatis-PageHelper@c692616c5b (2026-09-08). Data as JSON: /api/errors/c20fed553bfe34dd. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/com/github/pagehelper/cache/CacheFactory.java:69

                return new GuavaCache<K, V>(properties, prefix);
            } catch (Throwable t) {
                return new SimpleCache<K, V>(properties, prefix);
            }
        } else {
            try {
                Class<? extends Cache> clazz = (Class<? extends Cache>) Class.forName(sqlCacheClass);
                try {
                    Constructor<? extends Cache> constructor = clazz.getConstructor(Properties.class, String.class);
                    return constructor.newInstance(properties, prefix);
                } catch (Exception e) {
                    Cache cache = clazz.newInstance();
                    if (cache instanceof PageProperties) {
                        ((PageProperties) cache).setProperties(properties);
                    }
                    return cache;
                }
            } catch (Throwable t) {
                throw new PageException("Created Sql Cache [" + sqlCacheClass + "] Error", t);
            }
        }
    }

}

View on GitHub (pinned to c692616c5b)