apache/shardingsphere · error · ServiceProviderNotFoundException

SPI:1

SPI:1

Error message

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

What it means

ServiceProviderNotFoundException (error code family 'SPI') thrown by ShardingSphereURLLoadEngine.loadContent when the JDBC URL's source type matches neither a ShardingSphereLocalFileURLLoader nor a ShardingSphereModeConfigurationURLLoader SPI implementation. The message names the SPI interface and the requested type; code SPI:1 marks it as an extension-point resolution failure.

Source

Thrown at jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereURLLoadEngine.java:57

    private final ShardingSphereURL url;
    
    /**
     * Load configuration content.
     *
     * @return loaded content
     * @throws ServiceProviderNotFoundException service provider not found exception
     */
    public Object loadContent() {
        Optional<ShardingSphereLocalFileURLLoader> localFileURLLoader = TypedSPILoader.findService(ShardingSphereLocalFileURLLoader.class, url.getSourceType());
        if (localFileURLLoader.isPresent()) {
            Collection<String> lines = Arrays.asList(localFileURLLoader.get().load(url.getConfigurationSubject(), url.getQueryProps()).split(System.lineSeparator()));
            return URLArgumentLineRender.render(lines, URLArgumentPlaceholderTypeFactory.valueOf(url.getQueryProps()));
        }
        Optional<ShardingSphereModeConfigurationURLLoader> modeConfigURLLoader = TypedSPILoader.findService(ShardingSphereModeConfigurationURLLoader.class, url.getSourceType());
        if (modeConfigURLLoader.isPresent()) {
            return modeConfigURLLoader.get().load(url.getConfigurationSubject(), url.getQueryProps());
        }
        throw new ServiceProviderNotFoundException(ShardingSphereModeConfigurationURLLoader.class, url.getSourceType());
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Correct the URL to a supported form, e.g. jdbc:shardingsphere:classpath:config.yaml or jdbc:shardingsphere:absolutepath:/etc/ss/config.yaml.
2. Add the dependency that provides the needed loader (e.g. shardingsphere-cluster-mode-repository-etcd/zookeeper for mode-backed URLs).
3. If the URL type is custom, implement the SPI and register it via META-INF/services.
4. Verify the driver version supports the URL type you use (check docs for your release).

Example fix

# before
jdbc:shardingsphere:zookeeper:127.0.0.1:2181 # without mode-repository dependency
# after
# add shardingsphere-cluster-mode-repository-zookeeper, keep URL
jdbc:shardingsphere:classpath:sharding.yaml

// validate URL prefix before connecting
if (!url.matches("jdbc:shardingsphere:(classpath|absolutepath|file|jdbc|apollo|zookeeper|etcd)[:].+")) throw new IllegalArgumentException(url);

catch (ServiceProviderNotFoundException ex) { fail configuration startup with URL and supported types in message; }

When it happens

Trigger: Using a jdbc:shardingsphere:... URL whose scheme/type segment (e.g. 'classpath:...', 'apollo:...', 'etcd:...') has no matching SPI loader on the classpath — unsupported type string, typo, or the optional module providing that loader is missing.

Common situations: Typo in the URL type prefix; upgrading to 5.x URL format (jdbc:shardingsphere:classpath:... vs the old absolute-path style) without the right modules; using a mode-config source (zookeeper/etcd) without including the corresponding mode-artifact dependency; custom URL loaders not registered via ServiceLoader.

Related errors

• 0
• SPI:1
• getURL
• Unknown stream channel type `%s`.
• 400

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