{"record":{"id":"897c097ef32384d3","repo":"apache/shardingsphere","slug":"proxy-00001","errorCode":"PROXY-00001","errorMessage":"Load database server info failed.","messagePattern":"Load database server info failed\\.","errorType":"exception","errorClass":"DatabaseServerLoadingException","httpStatus":null,"severity":"critical","filePath":"proxy/bootstrap/src/main/java/org/apache/shardingsphere/proxy/database/DatabaseServerInfo.java","lineNumber":44,"sourceCode":"import java.sql.SQLException;\n\n/**\n * Database server info.\n */\n@Getter\npublic final class DatabaseServerInfo {\n    \n    private final String databaseType;\n    \n    private final String databaseVersion;\n    \n    public DatabaseServerInfo(final DataSource dataSource) {\n        try (Connection connection = dataSource.getConnection()) {\n            DatabaseMetaData databaseMetaData = connection.getMetaData();\n            databaseType = databaseMetaData.getDatabaseProductName();\n            databaseVersion = databaseMetaData.getDatabaseProductVersion();\n        } catch (final SQLException ex) {\n            throw new DatabaseServerLoadingException(ex);\n        }\n    }\n    \n    @Override\n    public String toString() {\n        return String.format(\"Database type is `%s`, version is `%s`\", databaseType, databaseVersion);\n    }\n}\n","sourceCodeStart":26,"sourceCodeEnd":53,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/proxy/bootstrap/src/main/java/org/apache/shardingsphere/proxy/database/DatabaseServerInfo.java#L26-L53","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Check that the correct JDBC driver jar for the backend database exists in the proxy's lib directory and matches the configured URL scheme.","Fix credentials or URL in the storage unit configuration (governance center or server.yaml) and restart the proxy.","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.","Inspect the cause chain of DatabaseServerLoadingException in the proxy log for the underlying SQLException code to pinpoint network vs auth vs driver issues."],"exampleFix":"# before (storage unit with a dead backend URL)\nurl: jdbc:postgresql://wrong-host:5432/demo\n\n# after (corrected host, proxy starts cleanly)\nurl: jdbc:postgresql://db-primary.internal:5432/demo","handlingStrategy":"validation","validationCode":"// Before starting the proxy, verify every storage unit is reachable\ntry (Connection ignored = DriverManager.getConnection(url, user, password)) {\n    // reachable; startup version probe will succeed\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start backend databases before starting the ShardingSphere proxy.","Keep a pre-flight script that opens one JDBC connection per configured storage unit.","Keep driver jars in the proxy lib directory in sync with the configured URLs."],"tags":["proxy","startup","jdbc","connectivity","configuration"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}