{"record":{"id":"6939ef92f0c513e4","repo":"apache/shardingsphere","slug":"could-not-load-class-s","errorCode":null,"errorMessage":"Could not load class: %s","messagePattern":"Could not load class: (.+?)","errorType":"exception","errorClass":"ClassNotFoundException","httpStatus":null,"severity":"error","filePath":"features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/algorithm/sharding/classbased/ClassBasedShardingAlgorithmFactory.java","lineNumber":77,"sourceCode":"        return result;\n    }\n    \n    private static Class<?> loadClass(final String className) throws ClassNotFoundException {\n        ClassLoader[] classLoaders = new ClassLoader[]{\n                Thread.currentThread().getContextClassLoader(),\n                ClassBasedShardingAlgorithmFactory.class.getClassLoader(),\n                ClassLoader.getSystemClassLoader()\n        };\n        for (ClassLoader each : classLoaders) {\n            if (null != each) {\n                try {\n                    return Class.forName(className, true, each);\n                } catch (final ClassNotFoundException ex) {\n                    // Try next classloader\n                }\n            }\n        }\n        throw new ClassNotFoundException(\"Could not load class: \" + className);\n    }\n}\n","sourceCodeStart":59,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/algorithm/sharding/classbased/ClassBasedShardingAlgorithmFactory.java#L59-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nalgorithm:\n  type: CLASS_BASED\n  props:\n    strategy: STANDARD\n    algorithmClassName: com.ex.maping.OrderShardingAlgorithm\n# after (fix package typo)\n    algorithmClassName: com.ex.mapping.OrderShardingAlgorithm","handlingStrategy":"validation","validationCode":"Class<?> c = null;\nfor (ClassLoader cl : new ClassLoader[]{Thread.currentThread().getContextClassLoader(), ClassLoader.getSystemClassLoader()}) {\n    try { c = Class.forName(className, true, cl); break; } catch (ClassNotFoundException ignored) { }\n}\nif (c == null) throw new IllegalStateException(\"Custom sharding algorithm not on classpath: \" + className);","typeGuard":null,"tryCatchPattern":"catch (RuntimeException ex) { if (ex.getCause() instanceof ClassNotFoundException cnfe) { /* report missing jar/class */ } throw ex; }","preventionTips":["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"],"tags":["sharding","classpath","class-loading","deployment"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}