apache/dolphinscheduler · error · TaskException

SQL task prepareStatementAndBind error

Error message

SQL task prepareStatementAndBind error

What it means

prepareStatementAndBind creates the JDBC PreparedStatement and binds task parameters (parameter type DIRECT/PASSING via ParameterUtils). Any failure in SQL preprocessing, placeholder substitution, or parameter binding is wrapped as this TaskException.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-sql/src/main/java/org/apache/dolphinscheduler/plugin/task/sql/SqlTask.java:389

        try {
            PreparedStatement stmt = connection.prepareStatement(sqlBinds.getSql());
            if (timeoutFlag) {
                stmt.setQueryTimeout(taskExecutionContext.getTaskTimeout());
            }
            stmt.setMaxRows(sqlParameters.getLimit() <= 0 ? QUERY_LIMIT : sqlParameters.getLimit());
            Map<Integer, Property> params = sqlBinds.getParamsMap();
            if (params != null) {
                for (Map.Entry<Integer, Property> entry : params.entrySet()) {
                    Property prop = entry.getValue();
                    ParameterUtils.setInParameter(entry.getKey(), stmt, prop.getType(), prop.getValue());
                }
            }
            log.info("prepare statement replace sql : {}, sql parameters : {}", sqlBinds.getSql(),
                    sqlBinds.getParamsMap());
            sessionStatement = stmt;
            return stmt;
        } catch (Exception exception) {
            throw new TaskException("SQL task prepareStatementAndBind error", exception);
        }
    }

    /**
     * print replace sql
     *
     * @param content      content
     * @param formatSql    format sql
     * @param rgex         rgex
     * @param sqlParamsMap sql params map
     */
    private void printReplacedSql(String content, String formatSql, String rgex, Map<Integer, Property> sqlParamsMap) {
        // parameter print style
        log.info("after replace sql , preparing : {}", formatSql);
        StringBuilder logPrint = new StringBuilder("replaced sql , parameters:");
        if (sqlParamsMap == null) {
            log.info("printReplacedSql: sqlParamsMap is null.");
        } else {

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify every ${parameter} in the SQL is defined in the task's custom/switch parameters or incoming dependencies
2. Check the log line 'prepare statement replace sql' to see the final SQL after substitution and confirm it is valid
3. Run the substituted SQL directly against the database to reproduce the driver error
4. Fix parameter type mismatches (dates, numbers) or cast values in SQL

Example fix

// before
String sql = "SELECT * FROM t WHERE dt = '${dt}'"; // dt not defined -> substitution failure
// after
// define dt in task custom parameters or use:
String sql = "SELECT * FROM t WHERE dt = ${dt}"; // with dt passed as task parameter

for (String key : extractPlaceholders(sql)) {
    if (!taskParameters.containsKey(key)) {
        throw new IllegalArgumentException("Missing SQL parameter: " + key);
    }
}

try {
    sqlTask.execute();
} catch (TaskException e) {
    if (e.getMessage().contains("prepareStatementAndBind")) {
        // log sqlBinds (visible in 'prepare statement replace sql' line) and fix params/SQL
    }
}

When it happens

Trigger: SQL with placeholders (${var} or ?) that cannot be resolved against available parameters; binding a parameter whose type is incompatible with the column; malformed SQL after parameter substitution; connection failures when obtaining the statement.

Common situations: Using ${param} in SQL when the task has no matching parameter defined (empty substitution); passing a string where the SQL expects a number; typo in parameter name in the custom config; datasource connection broken.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• GET_DATASOURCE_TABLES_ERROR
• Execute sql task failed
• Cancel sql task failed
• SQL column name conflict: duplicate column name '" + label +
• Query t_ds_process_instance error

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