apache/shardingsphere · error · ServiceProviderNotFoundException

SPI:1

SPI:1

Error message

No implementation class load from SPI '%s' with type '%s'.

What it means

TypedSPILoader.checkService iterates all implementations of a TypedSPI interface registered via ShardingSphereServiceLoader and matches the requested type (case-insensitively for strings, including type aliases). If no registered instance matches, it throws ServiceProviderNotFoundException ('No implementation class load from SPI ... with type ...', error code SPI:1) — the requested algorithm/dialect/feature type simply is not on the classpath or does not exist.

Source

Thrown at infra/spi/src/main/java/org/apache/shardingsphere/infra/spi/type/typed/TypedSPILoader.java:129

    }
    
    /**
     * Check service.
     *
     * @param serviceInterface typed SPI service interface
     * @param type type
     * @param props properties
     * @param <T> SPI class type
     * @throws ServiceProviderNotFoundException service provider not found server exception
     */
    public static <T extends TypedSPI> void checkService(final Class<T> serviceInterface, final Object type, final Properties props) {
        for (T each : ShardingSphereServiceLoader.getServiceInstances(serviceInterface)) {
            if (matchesType(type, each)) {
                each.init(null == props ? new Properties() : convertToStringTypedProperties(props));
                return;
            }
        }
        throw new ServiceProviderNotFoundException(serviceInterface, type);
    }
    
    private static boolean matchesType(final Object type, final TypedSPI instance) {
        Object instanceType = instance.getType();
        if (null == instanceType) {
            return false;
        }
        if (instanceType instanceof String && type instanceof String) {
            return instanceType.toString().equalsIgnoreCase(type.toString()) || instance.getTypeAliases().contains(type);
        }
        return instanceType.equals(type) || instance.getTypeAliases().contains(type);
    }
}

View on GitHub (pinned to e952770a21)

Solutions

  1. Fix the type value in configuration to exactly match the implementation's getType() (or one of its getTypeAliases()); string types match case-insensitively.
  2. Add the module/jar containing the implementation and its META-INF/services/<SPI interface> registration file to the classpath.
  3. For custom implementations, ensure the provider file names the class and getType() returns the configured value.

Example fix

# before (custom SPI not registered)
# src/main/resources/META-INF/services missing
algorithm: custom-hash: type: MY_HASH

# after
# file src/main/resources/META-INF/services/org.apache.shardingsphere.sharding.spi.ShardingAlgorithm:
#   com.example.MyHashShardingAlgorithm  (getType() returns "MY_HASH")
Defensive patterns

Strategy: validation

Validate before calling

boolean registered = ShardingSphereServiceLoader.getServiceInstances(ShardingAlgorithm.class).stream()
        .map(a -> ((TypedSPI) a).getType().toString())
        .anyMatch(t -> t.equalsIgnoreCase(configuredType));
if (!registered) { fail fast with the list of available types; }

Try / catch

try { TypedSPILoader.checkService(iface, type, props); } catch (ServiceProviderNotFoundException e) { /* list available types, fix config or classpath */ }

Prevention

When it happens

Trigger: Configuring a sharding/encryption key-generate algorithm, database dialect, or other TypedSPI extension with a type string that no registered implementation exposes — typos ('CLS_MOD' vs 'CLASS_BASED'), missing module/dependency jar, or a custom implementation lacking the META-INF/services registration or expected getType() value.

Common situations: Custom algorithm classes shipped without SPI registration files; dropping a dialect or feature module from the proxy distribution; renaming types between ShardingSphere versions; case/alias mismatches in YAML rule configuration.

Related errors

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