apache/dolphinscheduler · error · SQLException

Create adhoc connection error

Error message

Create adhoc connection error

What it means

BaseAdHocDataSourceClient.getConnection() wraps any failure from the underlying datasource plugin's processor when opening a non-pooled JDBC connection into a generic SQLException with message 'Create adhoc connection error'. The real cause is chained, so it could be a driver missing, bad credentials, unreachable host, etc.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/client/BaseAdHocDataSourceClient.java:43

import java.sql.Connection;
import java.sql.SQLException;

public abstract class BaseAdHocDataSourceClient implements AdHocDataSourceClient {

    private final BaseConnectionParam baseConnectionParam;
    private final DbType dbType;

    protected BaseAdHocDataSourceClient(BaseConnectionParam baseConnectionParam, DbType dbType) {
        this.baseConnectionParam = baseConnectionParam;
        this.dbType = dbType;
    }

    @Override
    public Connection getConnection() throws SQLException {
        try {
            return DataSourcePluginManager.getDataSourceProcessor(dbType).getConnection(baseConnectionParam);
        } catch (Exception e) {
            throw new SQLException("Create adhoc connection error", e);
        }
    }

    @Override
    public void close() {
        // do nothing
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Read the chained 'Caused by' to find the real failure
2. Verify host/port/database/credentials in the datasource config
3. Ensure the datasource plugin module (and its JDBC driver dependency) is deployed
4. Test connectivity to the DB host from the scheduler node (telnet/nc)
5. Check that the plugin's createConnectionParams were built correctly (no null jdbcUrl)

Example fix

// before: swallow generic error
Connection c = provider.getAdHocConnection(dbType, param);
// after: log full cause chain
catch (SQLException e) {
  logger.error("adhoc connection failed", e); // inspect causes
  throw e;
}

if (StringUtils.isBlank(param.getHost()) || param.getPort() == null) throw new IllegalArgumentException("incomplete datasource params");

try { Connection c = provider.getAdHocConnection(dbType, connParam); } catch (SQLException e) { logger.error("adhoc connection failed", e); /* inspect root cause */ throw new RuntimeException(e.getCause()); }

When it happens

Trigger: Calling getAdHocConnection()/getConnection() for a datasource whose plugin processor throws (driver class not found, malformed JDBC URL, network failure, wrong credentials).

Common situations: Missing JDBC driver jar in the plugin/Classpath, wrong host/port/database in datasource form, firewall blocking the DB, Kerberos/Hive connection failures.

Related errors

• DATASOURCE_CONNECT_FAILED
• datasource other params: + entry.getKey() + illegal
• 20016
• Can not find any datasource by name %s
• Get more than one datasource by name %s

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