{"record":{"id":"2b9c596cb25a72a9","repo":"apache/dolphinscheduler","slug":"connection-test-failure","errorCode":"CONNECTION_TEST_FAILURE","errorMessage":"Status.CONNECTION_TEST_FAILURE","messagePattern":"Status\\.CONNECTION_TEST_FAILURE","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/DataSourceServiceImpl.java","lineNumber":279,"sourceCode":"        return datasourceList;\n    }\n\n    @Override\n    public void verifyDataSourceName(String name) {\n        List<DataSource> dataSourceList = dataSourceDao.queryDataSourceByName(name);\n        if (dataSourceList != null && !dataSourceList.isEmpty()) {\n            throw new ServiceException(Status.DATASOURCE_EXIST);\n        }\n    }\n\n    @Override\n    public void checkConnection(DbType type, ConnectionParam connectionParam) {\n        DataSourceProcessor sshDataSourceProcessor = DataSourceUtils.getDatasourceProcessor(type);\n        boolean connectivity = sshDataSourceProcessor.checkDataSourceConnectivity(connectionParam);\n        if (connectivity) {\n            return;\n        }\n        throw new ServiceException(Status.CONNECTION_TEST_FAILURE);\n    }\n\n    @Override\n    public void connectionTest(User loginUser, int id) {\n        DataSource dataSource = dataSourceDao.queryById(id);\n\n        if (dataSource == null) {\n            throw new ServiceException(Status.RESOURCE_NOT_EXIST);\n        }\n\n        if (!canOperatorPermissions(loginUser, new Object[]{id}, AuthorizationType.DATASOURCE,\n                ApiFuncIdentificationConstant.DATASOURCE)) {\n            throw new ServiceException(Status.USER_NO_OPERATION_PERM);\n        }\n\n        checkConnection(dataSource.getType(),\n                DataSourceUtils.buildConnectionParams(dataSource.getType(), dataSource.getConnectionParams()));\n    }","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/DataSourceServiceImpl.java#L261-L297","documentation":"Thrown by checkConnection when the data source processor reports that a test connection to the target database failed (checkDataSourceConnectivity returned false). Mapped to Status.CONNECTION_TEST_FAILURE.","triggerScenarios":"POST /datasources/connect or connectionTest reaching a host that is reachable-resolving but refuses/fails the JDBC handshake: wrong port, wrong password, DB down, firewall drop, disabled TLS, or driver rejecting the URL.","commonSituations":"Database behind a firewall not open from the API server host; expired DB credentials; wrong host/port in the data source form; DB max connections exhausted; DNS resolving to a wrong IP in containerized deployments.","solutions":["Test connectivity from the API server host: nc/telnet to the DB host and port","Re-enter the username/password and host/port in the data source form and re-test","Check the DB server logs and DolphinScheduler API server logs for the underlying JDBC error","Verify network/firewall/ security-group rules allow the API server to reach the DB","Confirm the JDBC URL parameters (SSL mode, database name) are valid"],"exampleFix":"// before\nnew MySQLParam(\"10.0.0.5\", 3307, \"db\", \"user\", \"pass\"); // wrong port -> connectivity false\n// after\nnew MySQLParam(\"10.0.0.5\", 3306, \"db\", \"user\", \"pass\");","handlingStrategy":"try-catch","validationCode":"// before creating: check host/port reachability from the API server\ntry (Socket s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); reachable = true; }","typeGuard":null,"tryCatchPattern":"try { service.checkConnection(type, connParams); } catch (ServiceException e) { if (e.getCode() == Status.CONNECTION_TEST_FAILURE.getCode()) { logJdbcDiagnostics(); } throw e; }","preventionTips":["Open firewall/security-group paths from API server to DB","Validate credentials and JDBC URL before saving","Test connectivity from inside the same network as the API server","Watch for DB max-connection exhaustion"],"tags":["network","connectivity","database"],"backgroundTag":"connection-refused","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}