{"record":{"id":"14869200b6652f85","repo":"apache/shardingsphere","slug":"sharding-algorithm-class-s-should-be-implement","errorCode":null,"errorMessage":"Sharding algorithm class '%s' should be implement '%s'.","messagePattern":"Sharding algorithm class '(.+?)' should be implement '(.+?)'\\.","errorType":"exception","errorClass":"ShardingAlgorithmClassImplementationException","httpStatus":null,"severity":"error","filePath":"features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/algorithm/sharding/classbased/ClassBasedShardingAlgorithmFactory.java","lineNumber":49,"sourceCode":"@NoArgsConstructor(access = AccessLevel.PRIVATE)\npublic final class ClassBasedShardingAlgorithmFactory {\n    \n    /**\n     * Create sharding algorithm.\n     *\n     * @param shardingAlgorithmClassName sharding algorithm class name\n     * @param superShardingAlgorithmClass sharding algorithm super class\n     * @param props properties\n     * @param <T> class generic type\n     * @return sharding algorithm instance\n     * @throws ShardingAlgorithmClassImplementationException sharding algorithm class implementation exception\n     */\n    @SuppressWarnings(\"unchecked\")\n    @SneakyThrows(ReflectiveOperationException.class)\n    public static <T extends ShardingAlgorithm> T newInstance(final String shardingAlgorithmClassName, final Class<T> superShardingAlgorithmClass, final Properties props) {\n        Class<?> algorithmClass = loadClass(shardingAlgorithmClassName);\n        if (!superShardingAlgorithmClass.isAssignableFrom(algorithmClass)) {\n            throw new ShardingAlgorithmClassImplementationException(shardingAlgorithmClassName, superShardingAlgorithmClass);\n        }\n        T result = (T) algorithmClass.getDeclaredConstructor().newInstance();\n        result.init(convertToStringTypedProperties(props));\n        return result;\n    }\n    \n    private static Properties convertToStringTypedProperties(final Properties props) {\n        Properties result = new Properties();\n        props.forEach((key, value) -> result.setProperty(key.toString(), null == value ? null : value.toString()));\n        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        };","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/algorithm/sharding/classbased/ClassBasedShardingAlgorithmFactory.java#L31-L67","documentation":"Thrown by ClassBasedShardingAlgorithmFactory.newInstance when the class given as strategy/algorithm in a CLASS_BASED sharding algorithm loads successfully but does not implement/extend the required ShardingAlgorithm subtype (StandardShardingAlgorithm, KeyGenerateAlgorithm, ComplexShardingAlgorithm, HintShardingAlgorithm). The framework reflects on the class and rejects it before instantiation.","triggerScenarios":"Configuring type: CLASS_BASED with strategy: STANDARD and a custom class that implements the wrong interface (e.g. implements ComplexKeysShardingAlgorithm while strategy says STANDARD), or extends an obsolete 4.x API class like PreciseShardingAlgorithm.","commonSituations":"Upgrading from ShardingSphere 4.x to 5.x where the old Precise/ShardingAlgorithm interfaces were replaced; copying a sample class for a different strategy type; typo in the strategy value mapping the class to the wrong super type.","solutions":["Make the custom class implement the interface matching the configured strategy (STANDARD -> StandardShardingAlgorithm, COMPLEX -> ComplexKeysShardingAlgorithm, HINT -> HintShardingAlgorithm) and move doSharding logic accordingly","If migrating from 4.x, port PreciseShardingAlgorithm.doSharding into StandardShardingAlgorithm.doSharding and RangeShardingAlgorithm.doSharding into the range overload","Add a public no-arg constructor and implement getType()/init(Properties) required by the SPI","Verify the strategy: value in the CLASS_BASED props matches the interface actually implemented"],"exampleFix":"// before (4.x style)\npublic final class OrderShardingAlgorithm implements PreciseShardingAlgorithm<Long> {\n    public String doSharding(Collection<String> targets, PreciseShardingValue<Long> v) { ... }\n}\n// after\npublic final class OrderShardingAlgorithm implements StandardShardingAlgorithm<Comparable<?>> {\n    @Override\n    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<Comparable<?>> shardingValue) { ... }\n    @Override\n    public Collection<String> doSharding(Collection<String> availableTargetNames, RangeShardingValue<Comparable<?>> shardingValue) { ... }\n    @Override\n    public String getType() { return \"CLASS_BASED\"; }\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean implementsStrategy(Class<?> clazz, Class<? extends ShardingAlgorithm> required) {\n    return required.isAssignableFrom(clazz) && hasNoArgConstructor(clazz);\n}","tryCatchPattern":"catch (ShardingAlgorithmClassImplementationException ex) { fail deployment with clear message naming class vs required interface }","preventionTips":["Write a unit test that loads each custom class via ClassBasedShardingAlgorithmFactory.newInstance before shipping","Pin the ShardingSphere version in the custom algorithm's build to match the runtime","Run a config smoke test (activate rules) in a staging proxy before production"],"tags":["sharding","class-based","algorithm","upgrade","reflection"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}