apache/shardingsphere · critical · DatabaseServerLoadingException

PROXY-00001

PROXY-00001

Error message

Load database server info failed.

What it means

Thrown by the DatabaseServerInfo constructor (proxy/bootstrap), which opens a JDBC connection during proxy startup and reads DatabaseMetaData.getDatabaseProductName()/getDatabaseProductVersion(). Any SQLException from getConnection() or the metadata calls is wrapped in DatabaseServerLoadingException (error code PROXY-00001, 'Load database server info failed.'). This happens inside ShardingSphereProxyVersion.setDatabaseVersion, which runs for every database that has a storage unit matching its protocol type, so one unreachable backend aborts the startup version banner.

Source

Thrown at proxy/bootstrap/src/main/java/org/apache/shardingsphere/proxy/database/DatabaseServerInfo.java:44

import java.sql.SQLException;

/**
 * Database server info.
 */
@Getter
public final class DatabaseServerInfo {
    
    private final String databaseType;
    
    private final String databaseVersion;
    
    public DatabaseServerInfo(final DataSource dataSource) {
        try (Connection connection = dataSource.getConnection()) {
            DatabaseMetaData databaseMetaData = connection.getMetaData();
            databaseType = databaseMetaData.getDatabaseProductName();
            databaseVersion = databaseMetaData.getDatabaseProductVersion();
        } catch (final SQLException ex) {
            throw new DatabaseServerLoadingException(ex);
        }
    }
    
    @Override
    public String toString() {
        return String.format("Database type is `%s`, version is `%s`", databaseType, databaseVersion);
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Verify the backend database is reachable from the proxy host with the exact JDBC URL, user and password configured in the storage unit (e.g. test with a standalone JDBC client or the backend's own CLI).
2. Check that the correct JDBC driver jar for the backend database exists in the proxy's lib directory and matches the configured URL scheme.
3. Fix credentials or URL in the storage unit configuration (governance center or server.yaml) and restart the proxy.
4. If the backend is intentionally unavailable at startup, start the backend first, or remove/defer loading of that database so the version probe can succeed.
5. Inspect the cause chain of DatabaseServerLoadingException in the proxy log for the underlying SQLException code to pinpoint network vs auth vs driver issues.

Example fix

# before (storage unit with a dead backend URL)
url: jdbc:postgresql://wrong-host:5432/demo

# after (corrected host, proxy starts cleanly)
url: jdbc:postgresql://db-primary.internal:5432/demo

// Before starting the proxy, verify every storage unit is reachable
try (Connection ignored = DriverManager.getConnection(url, user, password)) {
    // reachable; startup version probe will succeed
}

When it happens

Trigger: ShardingSphereProxyVersion.setVersion() runs at proxy bootstrap; findDataSourceByProtocolType() picks the first storage unit whose type equals the database protocol type, and new DatabaseServerInfo(dataSource) calls dataSource.getConnection(), connection.getMetaData().getDatabaseProductName() and getDatabaseProductVersion(). Any of these throwing SQLException (bad URL, wrong credentials, network unreachable, driver missing, backend down) produces this error.

Common situations: server.yaml/governance metadata references a storage unit whose JDBC URL is wrong; backend database is not up when the proxy starts; username/password in the storage unit config is incorrect; JDBC driver jar missing from the proxy lib directory; firewall/DNS prevents reaching the backend; backend denies too many connections during restart.

Related errors

• Duplicate rule tag `!%s` in file `%s`
• 13000
• 2
• SPI:1
• 0

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