apache/shardingsphere · critical · SQLWrapperException

5

5

Error message

Underlying SQL state: %s, underlying error code: %s.

What it means

SQLWrapperException thrown by DatabaseTypeEngine.getStorageType when opening a connection to the provided DataSource to read database metadata fails: dataSource.getConnection() or metadata access throws SQLException, which is wrapped (message surfaces the underlying SQLState and vendor error code). This utility resolves the storage DatabaseType by connecting once; failure usually means the data source itself is unreachable or misconfigured.

Source

Thrown at infra/common/src/main/java/org/apache/shardingsphere/infra/database/DatabaseTypeEngine.java:103

    
    private static Map<String, DataSource> getDataSources(final DatabaseConfiguration databaseConfig) {
        return databaseConfig.getStorageUnits().entrySet().stream()
                .collect(Collectors.toMap(Entry::getKey, entry -> entry.getValue().getDataSource(), (oldValue, currentValue) -> oldValue, LinkedHashMap::new));
    }
    
    /**
     * Get storage type.
     *
     * @param dataSource data source
     * @return storage type
     * @throws SQLWrapperException SQL wrapper exception
     * @throws RuntimeException Runtime exception
     */
    public static DatabaseType getStorageType(final DataSource dataSource) {
        try (Connection connection = dataSource.getConnection()) {
            return DatabaseTypeFactory.get(connection.getMetaData());
        } catch (final SQLException ex) {
            throw new SQLWrapperException(ex);
        }
    }
    
    /**
     * Get default storage type.
     *
     * @return default storage type
     */
    public static DatabaseType getDefaultStorageType() {
        return TypedSPILoader.getService(DatabaseType.class, DEFAULT_DATABASE_TYPE);
    }
}

View on GitHub (pinned to e952770a21)

Solutions

  1. Verify connectivity with the same URL/credentials outside ShardingSphere (e.g. a plain JDBC probe or psql/mysql client).
  2. Fix the data source configuration: URL syntax, driver class, username/password, and make sure the driver jar is on the classpath.
  3. If the failure is transient (pool exhaustion, brief outage), retry the operation after the database is reachable.
  4. Check the wrapped SQLException's SQLState/error code in the cause chain for the database's specific reason.

Example fix

# before: unreachable host / bad credentials
url: jdbc:postgresql://db.prod.internal:5432/shop?user=app&password=wrong

# after: verified reachable host and credentials
url: jdbc:postgresql://db.prod.internal:5432/shop
username: app
password: correct_secret
Defensive patterns

Strategy: retry

Validate before calling

// Probe connectivity before asking ShardingSphere to resolve the storage type
try (Connection c = dataSource.getConnection();
     var stmt = c.createStatement();
     var rs = stmt.executeQuery("SELECT 1")) {
    // reachable — safe to proceed
} catch (SQLException e) {
    throw new IllegalStateException("Storage unit unreachable: " + jdbcUrl, e);
}

Try / catch

int attempts = 0;
while (true) {
    try {
        return DatabaseTypeEngine.getStorageType(dataSource);
    } catch (final SQLWrapperException ex) {
        SQLException cause = (SQLException) ex.getCause();
        if (++attempts >= 3 || !isTransient(cause)) { throw ex; }
        backoff(attempts);
    }
}

Prevention

When it happens

Trigger: Calling contexts that resolve a storage type from a raw DataSource (e.g. adding a storage unit, JDBC mode metadata loading) when the database is down, credentials are wrong, URL/driver is invalid, or a pool rejects the connection (timeout, pool exhausted).

Common situations: Startup or REGISTER STORAGE UNIT with an unreachable DB host; wrong username/password; JDBC URL with bad syntax or missing driver on the classpath; network/firewall blocking the database port; connection-pool limits hit during metadata refresh.

Related errors

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