apache/shardingsphere · critical · DriverRegisterException

0

0

Error message

Can not register driver.

What it means

DriverRegisterException (an RuntimeException) thrown from ShardingSphereDriver's static initializer when DriverManager.registerDriver(new ShardingSphereDriver()) fails with SQLException. Because it happens in a <clinit> block, it surfaces as ExceptionInInitializerError followed by NoClassDefFoundError on later class use. Registration almost never fails unless the JDBC infrastructure itself is broken.

Solutions

1. Verify the ShardingSphere jdbc artifact and its dependencies are complete and match your version (mvn dependency:tree; check for jar corruption).
2. Remove duplicate/conflicting shardingsphere-driver jars from the classpath.
3. If a SecurityManager is active, grant the permission needed for DriverManager.registerDriver or disable it.
4. Rebuild/replace the fat jar with a correct shading configuration that keeps META-INF/services and driver classes intact.

Example fix

// before
classpath: shardingsphere-jdbc-5.5.0.jar (corrupted) -> ExceptionInInitializerError
// after
classpath: verified shardingsphere-jdbc-5.5.0.jar + aligned infra modules
Class.forName("org.apache.shardingsphere.driver.ShardingSphereDriver");

try { Class.forName("org.apache.shardingsphere.driver.ShardingSphereDriver"); } catch (Throwable t) { failFast("driver jar broken: " + t); }

When it happens

Trigger: First class-loading of ShardingSphereDriver (e.g. Class.forName("org.apache.shardingsphere.driver.ShardingSphereDriver") or DriverManager scanning) while DriverManager.registerDriver throws — typically a damaged JDK/JDBC setup, a SecurityManager refusing driver registration, or a conflicting/corrupted driver jar on the classpath.

Common situations: Corrupted or incomplete ShardingSphere jdbc jar (missing classes); a custom SecurityManager or hardened container blocking DriverManager registration; shaded/fat-jar builds that mangle the driver classes; JDK migration issues; duplicated incompatible driver versions resolved by the classpath.

Related errors

• 0
• 0
• 0
• 0
• 13000

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

Appendix: source

Thrown at jdbc/src/main/java/org/apache/shardingsphere/driver/ShardingSphereDriver.java:50

/**
 * ShardingSphere driver.
 */
@SuppressWarnings("UseOfJDBCDriverClass")
public final class ShardingSphereDriver implements Driver {
    
    private static final String DRIVER_URL_PREFIX = "jdbc:shardingsphere:";
    
    private static final int MAJOR_DRIVER_VERSION = 5;
    
    private static final int MINOR_DRIVER_VERSION = 5;
    
    private static final DriverDataSourceCache DATA_SOURCE_CACHE = new DriverDataSourceCache();
    
    static {
        try {
            DriverManager.registerDriver(new ShardingSphereDriver());
        } catch (final SQLException ex) {
            throw new DriverRegisterException(ex);
        }
    }
    
    @HighFrequencyInvocation(canBeCached = true)
    @Override
    public Connection connect(final String url, final Properties info) throws SQLException {
        return acceptsURL(url) ? DATA_SOURCE_CACHE.get(url, DRIVER_URL_PREFIX).getConnection() : null;
    }
    
    @Override
    public boolean acceptsURL(final String url) {
        return null != url && url.startsWith(DRIVER_URL_PREFIX);
    }
    
    @Override
    public DriverPropertyInfo[] getPropertyInfo(final String url, final Properties info) {
        return new DriverPropertyInfo[0];
    }

View on GitHub (pinned to e952770a21)