{"record":{"id":"33cdd2e03d20187b","repo":"apache/dolphinscheduler","slug":"sql-task-preparestatementandbind-error","errorCode":null,"errorMessage":"SQL task prepareStatementAndBind error","messagePattern":"SQL task prepareStatementAndBind error","errorType":"exception","errorClass":"TaskException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-task-plugin/dolphinscheduler-task-sql/src/main/java/org/apache/dolphinscheduler/plugin/task/sql/SqlTask.java","lineNumber":389,"sourceCode":"        try {\n            PreparedStatement stmt = connection.prepareStatement(sqlBinds.getSql());\n            if (timeoutFlag) {\n                stmt.setQueryTimeout(taskExecutionContext.getTaskTimeout());\n            }\n            stmt.setMaxRows(sqlParameters.getLimit() <= 0 ? QUERY_LIMIT : sqlParameters.getLimit());\n            Map<Integer, Property> params = sqlBinds.getParamsMap();\n            if (params != null) {\n                for (Map.Entry<Integer, Property> entry : params.entrySet()) {\n                    Property prop = entry.getValue();\n                    ParameterUtils.setInParameter(entry.getKey(), stmt, prop.getType(), prop.getValue());\n                }\n            }\n            log.info(\"prepare statement replace sql : {}, sql parameters : {}\", sqlBinds.getSql(),\n                    sqlBinds.getParamsMap());\n            sessionStatement = stmt;\n            return stmt;\n        } catch (Exception exception) {\n            throw new TaskException(\"SQL task prepareStatementAndBind error\", exception);\n        }\n    }\n\n    /**\n     * print replace sql\n     *\n     * @param content      content\n     * @param formatSql    format sql\n     * @param rgex         rgex\n     * @param sqlParamsMap sql params map\n     */\n    private void printReplacedSql(String content, String formatSql, String rgex, Map<Integer, Property> sqlParamsMap) {\n        // parameter print style\n        log.info(\"after replace sql , preparing : {}\", formatSql);\n        StringBuilder logPrint = new StringBuilder(\"replaced sql , parameters:\");\n        if (sqlParamsMap == null) {\n            log.info(\"printReplacedSql: sqlParamsMap is null.\");\n        } else {","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-task-plugin/dolphinscheduler-task-sql/src/main/java/org/apache/dolphinscheduler/plugin/task/sql/SqlTask.java#L371-L407","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify every ${parameter} in the SQL is defined in the task's custom/switch parameters or incoming dependencies","Check the log line 'prepare statement replace sql' to see the final SQL after substitution and confirm it is valid","Run the substituted SQL directly against the database to reproduce the driver error","Fix parameter type mismatches (dates, numbers) or cast values in SQL"],"exampleFix":"// before\nString sql = \"SELECT * FROM t WHERE dt = '${dt}'\"; // dt not defined -> substitution failure\n// after\n// define dt in task custom parameters or use:\nString sql = \"SELECT * FROM t WHERE dt = ${dt}\"; // with dt passed as task parameter","handlingStrategy":"validation","validationCode":"for (String key : extractPlaceholders(sql)) {\n    if (!taskParameters.containsKey(key)) {\n        throw new IllegalArgumentException(\"Missing SQL parameter: \" + key);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    sqlTask.execute();\n} catch (TaskException e) {\n    if (e.getMessage().contains(\"prepareStatementAndBind\")) {\n        // log sqlBinds (visible in 'prepare statement replace sql' line) and fix params/SQL\n    }\n}","preventionTips":["Keep parameter names in SQL identical to task parameter keys","Preview the substituted SQL in the UI before saving","Cast parameters in SQL (CAST(? AS DATE)) to avoid driver type errors"],"tags":["sql","jdbc","parameter-binding"],"backgroundTag":"sql-query-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"}