apache/dolphinscheduler · error · ServiceException

CONNECTION_TEST_FAILURE

CONNECTION_TEST_FAILURE

Error message

Status.CONNECTION_TEST_FAILURE

What it means

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.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/DataSourceServiceImpl.java:279

        return datasourceList;
    }

    @Override
    public void verifyDataSourceName(String name) {
        List<DataSource> dataSourceList = dataSourceDao.queryDataSourceByName(name);
        if (dataSourceList != null && !dataSourceList.isEmpty()) {
            throw new ServiceException(Status.DATASOURCE_EXIST);
        }
    }

    @Override
    public void checkConnection(DbType type, ConnectionParam connectionParam) {
        DataSourceProcessor sshDataSourceProcessor = DataSourceUtils.getDatasourceProcessor(type);
        boolean connectivity = sshDataSourceProcessor.checkDataSourceConnectivity(connectionParam);
        if (connectivity) {
            return;
        }
        throw new ServiceException(Status.CONNECTION_TEST_FAILURE);
    }

    @Override
    public void connectionTest(User loginUser, int id) {
        DataSource dataSource = dataSourceDao.queryById(id);

        if (dataSource == null) {
            throw new ServiceException(Status.RESOURCE_NOT_EXIST);
        }

        if (!canOperatorPermissions(loginUser, new Object[]{id}, AuthorizationType.DATASOURCE,
                ApiFuncIdentificationConstant.DATASOURCE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);
        }

        checkConnection(dataSource.getType(),
                DataSourceUtils.buildConnectionParams(dataSource.getType(), dataSource.getConnectionParams()));
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Test connectivity from the API server host: nc/telnet to the DB host and port
  2. Re-enter the username/password and host/port in the data source form and re-test
  3. Check the DB server logs and DolphinScheduler API server logs for the underlying JDBC error
  4. Verify network/firewall/ security-group rules allow the API server to reach the DB
  5. Confirm the JDBC URL parameters (SSL mode, database name) are valid

Example fix

// before
new MySQLParam("10.0.0.5", 3307, "db", "user", "pass"); // wrong port -> connectivity false
// after
new MySQLParam("10.0.0.5", 3306, "db", "user", "pass");
Defensive patterns

Strategy: try-catch

Validate before calling

// before creating: check host/port reachability from the API server
try (Socket s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); reachable = true; }

Try / catch

try { service.checkConnection(type, connParams); } catch (ServiceException e) { if (e.getCode() == Status.CONNECTION_TEST_FAILURE.getCode()) { logJdbcDiagnostics(); } throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/2b9c596cb25a72a9. Report an issue: GitHub.