What causes "Could not load class: %s" in apache/shardingsphere?

Verify the exact fully-qualified class name in props matches the compiled class (copy from the JAR entry)

apache/shardingsphere · error · ClassNotFoundException

Could not load class: %s

Error message

Could not load class: %s

What it means

Thrown by ClassBasedShardingAlgorithmFactory.loadClass after Class.forName fails on all three attempted classloaders (thread context, factory's own, system). It surfaces as a reflective ClassNotFoundException (rethrown via @SneakyThrows) meaning the custom sharding algorithm class simply is not on any reachable classpath.

Source

Thrown at features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/algorithm/sharding/classbased/ClassBasedShardingAlgorithmFactory.java:77

        return result;
    }
    
    private static Class<?> loadClass(final String className) throws ClassNotFoundException {
        ClassLoader[] classLoaders = new ClassLoader[]{
                Thread.currentThread().getContextClassLoader(),
                ClassBasedShardingAlgorithmFactory.class.getClassLoader(),
                ClassLoader.getSystemClassLoader()
        };
        for (ClassLoader each : classLoaders) {
            if (null != each) {
                try {
                    return Class.forName(className, true, each);
                } catch (final ClassNotFoundException ex) {
                    // Try next classloader
                }
            }
        }
        throw new ClassNotFoundException("Could not load class: " + className);
    }
}

View on GitHub (pinned to e952770a21)

Solutions

Verify the exact fully-qualified class name in props matches the compiled class (copy from the JAR entry)
Copy the custom algorithm JAR into the Proxy's lib/ directory (or add to JDBC classpath) and restart
Rebuild the JAR against the same ShardingSphere version and confirm the class appears in jar tf output
Check for shade/relocation rules that moved the package and update the configured name

Example fix

# before
algorithm:
  type: CLASS_BASED
  props:
    strategy: STANDARD
    algorithmClassName: com.ex.maping.OrderShardingAlgorithm
# after (fix package typo)
    algorithmClassName: com.ex.mapping.OrderShardingAlgorithm

Defensive patterns

Strategy: validation

Validate before calling

Class<?> c = null;
for (ClassLoader cl : new ClassLoader[]{Thread.currentThread().getContextClassLoader(), ClassLoader.getSystemClassLoader()}) {
    try { c = Class.forName(className, true, cl); break; } catch (ClassNotFoundException ignored) { }
}
if (c == null) throw new IllegalStateException("Custom sharding algorithm not on classpath: " + className);

Try / catch

catch (RuntimeException ex) { if (ex.getCause() instanceof ClassNotFoundException cnfe) { /* report missing jar/class */ } throw ex; }

Prevention

Package custom algorithm jars into the deployment artifact and verify with jar tf in CI
Use a config test that loads all CLASS_BASED class names against the production classpath

When it happens

Trigger: Configuring CLASS_BASED with a fully-qualified class name that is misspelled, not compiled, or whose JAR is absent from the classpath of the running JDBC driver or Proxy instance.

Common situations: Forgetting to put the custom algorithm JAR into the proxy's /lib directory; package rename after refactoring; fat-jar shading renaming classes; class present in the app but not visible to the isolated classloader in Proxy mode; fat finger in the class name in YAML.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/6939ef92f0c513e4. Report an issue: GitHub.