{"record":{"id":"d315147cb435753b","repo":"apache/dolphinscheduler","slug":"create-adhoc-connection-error","errorCode":null,"errorMessage":"Create adhoc connection error","messagePattern":"Create adhoc connection error","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/client/BaseAdHocDataSourceClient.java","lineNumber":43,"sourceCode":"import java.sql.Connection;\nimport java.sql.SQLException;\n\npublic abstract class BaseAdHocDataSourceClient implements AdHocDataSourceClient {\n\n    private final BaseConnectionParam baseConnectionParam;\n    private final DbType dbType;\n\n    protected BaseAdHocDataSourceClient(BaseConnectionParam baseConnectionParam, DbType dbType) {\n        this.baseConnectionParam = baseConnectionParam;\n        this.dbType = dbType;\n    }\n\n    @Override\n    public Connection getConnection() throws SQLException {\n        try {\n            return DataSourcePluginManager.getDataSourceProcessor(dbType).getConnection(baseConnectionParam);\n        } catch (Exception e) {\n            throw new SQLException(\"Create adhoc connection error\", e);\n        }\n    }\n\n    @Override\n    public void close() {\n        // do nothing\n    }\n}\n","sourceCodeStart":25,"sourceCodeEnd":52,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/client/BaseAdHocDataSourceClient.java#L25-L52","documentation":"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.","triggerScenarios":"Calling getAdHocConnection()/getConnection() for a datasource whose plugin processor throws (driver class not found, malformed JDBC URL, network failure, wrong credentials).","commonSituations":"Missing JDBC driver jar in the plugin/Classpath, wrong host/port/database in datasource form, firewall blocking the DB, Kerberos/Hive connection failures.","solutions":["Read the chained 'Caused by' to find the real failure","Verify host/port/database/credentials in the datasource config","Ensure the datasource plugin module (and its JDBC driver dependency) is deployed","Test connectivity to the DB host from the scheduler node (telnet/nc)","Check that the plugin's createConnectionParams were built correctly (no null jdbcUrl)"],"exampleFix":"// before: swallow generic error\nConnection c = provider.getAdHocConnection(dbType, param);\n// after: log full cause chain\ncatch (SQLException e) {\n  logger.error(\"adhoc connection failed\", e); // inspect causes\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (StringUtils.isBlank(param.getHost()) || param.getPort() == null) throw new IllegalArgumentException(\"incomplete datasource params\");","typeGuard":null,"tryCatchPattern":"try { Connection c = provider.getAdHocConnection(dbType, connParam); } catch (SQLException e) { logger.error(\"adhoc connection failed\", e); /* inspect root cause */ throw new RuntimeException(e.getCause()); }","preventionTips":["Pre-verify DB connectivity from the scheduler host","Keep JDBC drivers deployed with the plugin","Log the full cause chain, not just the wrapper message"],"tags":["jdbc","datasource","connection"],"backgroundTag":"database-connection-failed","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"}