apache/shardingsphere · error · ShardingAlgorithmClassImplementationException

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

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.

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)

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

• Could not load class: %s
• Invalid %s, datetime pattern should be '%s', value is '%s'.
• Invalid %s, datetime pattern should be '%s', value is '%s'.
• 40
• 41

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