apache/shardingsphere · error · ShardingAlgorithmClassImplementationException

Sharding algorithm class

Error message

Sharding algorithm class '%s' should be implement '%s'.

What it means

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.

Solutions

1. Make the custom class implement the interface matching the configured strategy (STANDARD -> StandardShardingAlgorithm, COMPLEX -> ComplexKeysShardingAlgorithm, HINT -> HintShardingAlgorithm) and move doSharding logic accordingly
2. If migrating from 4.x, port PreciseShardingAlgorithm.doSharding into StandardShardingAlgorithm.doSharding and RangeShardingAlgorithm.doSharding into the range overload
3. Add a public no-arg constructor and implement getType()/init(Properties) required by the SPI
4. Verify the strategy: value in the CLASS_BASED props matches the interface actually implemented

Example fix

// before (4.x style)
public final class OrderShardingAlgorithm implements PreciseShardingAlgorithm<Long> {
    public String doSharding(Collection<String> targets, PreciseShardingValue<Long> v) { ... }
}
// after
public final class OrderShardingAlgorithm implements StandardShardingAlgorithm<Comparable<?>> {
    @Override
    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<Comparable<?>> shardingValue) { ... }
    @Override
    public Collection<String> doSharding(Collection<String> availableTargetNames, RangeShardingValue<Comparable<?>> shardingValue) { ... }
    @Override
    public String getType() { return "CLASS_BASED"; }
}

static boolean implementsStrategy(Class<?> clazz, Class<? extends ShardingAlgorithm> required) {
    return required.isAssignableFrom(clazz) && hasNoArgConstructor(clazz);
}

catch (ShardingAlgorithmClassImplementationException ex) { fail deployment with clear message naming class vs required interface }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 0
• 1
• 1
• 1
• 2

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

Appendix: source

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

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class ClassBasedShardingAlgorithmFactory {
    
    /**
     * Create sharding algorithm.
     *
     * @param shardingAlgorithmClassName sharding algorithm class name
     * @param superShardingAlgorithmClass sharding algorithm super class
     * @param props properties
     * @param <T> class generic type
     * @return sharding algorithm instance
     * @throws ShardingAlgorithmClassImplementationException sharding algorithm class implementation exception
     */
    @SuppressWarnings("unchecked")
    @SneakyThrows(ReflectiveOperationException.class)
    public static <T extends ShardingAlgorithm> T newInstance(final String shardingAlgorithmClassName, final Class<T> superShardingAlgorithmClass, final Properties props) {
        Class<?> algorithmClass = loadClass(shardingAlgorithmClassName);
        if (!superShardingAlgorithmClass.isAssignableFrom(algorithmClass)) {
            throw new ShardingAlgorithmClassImplementationException(shardingAlgorithmClassName, superShardingAlgorithmClass);
        }
        T result = (T) algorithmClass.getDeclaredConstructor().newInstance();
        result.init(convertToStringTypedProperties(props));
        return result;
    }
    
    private static Properties convertToStringTypedProperties(final Properties props) {
        Properties result = new Properties();
        props.forEach((key, value) -> result.setProperty(key.toString(), null == value ? null : value.toString()));
        return result;
    }
    
    private static Class<?> loadClass(final String className) throws ClassNotFoundException {
        ClassLoader[] classLoaders = new ClassLoader[]{
                Thread.currentThread().getContextClassLoader(),
                ClassBasedShardingAlgorithmFactory.class.getClassLoader(),
                ClassLoader.getSystemClassLoader()
        };

View on GitHub (pinned to e952770a21)