apache/dolphinscheduler · error · RuntimeException

Execute initialize sql file: " + sqlFilePath + " error

Error message

Execute initialize sql file: " + sqlFilePath + " error

What it means

UpgradeDao.initSchema executes sql/dolphinscheduler_<dbType>.sql via SqlScriptRunner to initialize the schema. Any exception while executing that SQL file (connection failure, syntax error, pre-existing tables) is rethrown as a RuntimeException 'Execute initialize sql file: <path> error' with the original exception as cause.

Source

Thrown at dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java:66

    @Autowired
    private DbType dbType;

    @Autowired
    private DatabaseDialect databaseDialect;

    /**
     * run init sql to init db schema
     */
    public void initSchema() {
        // Execute the dolphinscheduler full sql
        String sqlFilePath = String.format("sql/dolphinscheduler_%s.sql", dbType.getDb());
        SqlScriptRunner sqlScriptRunner = new SqlScriptRunner(dataSource, sqlFilePath);
        try {
            sqlScriptRunner.execute();
            log.info("Success execute the sql initialize file: {}", sqlFilePath);
        } catch (Exception ex) {
            throw new RuntimeException("Execute initialize sql file: " + sqlFilePath + " error", ex);
        }
    }

    public String getCurrentVersion(String versionName) {
        String sql = String.format("select version from %s", versionName);
        String version = null;
        try (
                Connection conn = dataSource.getConnection();
                PreparedStatement pstmt = conn.prepareStatement(sql);
                ResultSet rs = pstmt.executeQuery()) {
            if (rs.next()) {
                version = rs.getString(1);
            }
            return version;
        } catch (SQLException e) {
            log.error("Get current version from database error, sql: {}", sql, e);
            throw new RuntimeException("Get current version from database error, sql: " + sql, e);
        }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Read the cause exception to find the failing SQL statement, and fix that specific issue (drop conflicting objects or fix privileges).
  2. Verify sql/dolphinscheduler_<dbType>.sql exists on the classpath for your database type.
  3. Grant the DB user CREATE/DDL privileges, or run as a DBA account during init.
  4. If the script partially applied, drop the partially created objects (or use a clean schema) and re-run init.
Defensive patterns

Strategy: try-catch

Validate before calling

// verify the sql resource and empty target before init
assert UpgradeDao.class.getClassLoader().getResource("sql/dolphinscheduler_mysql.sql") != null : "init sql file missing from classpath";
// verify target schema has no existing DolphinScheduler tables

Try / catch

try {
    upgradeDao.initSchema();
} catch (RuntimeException e) {
    log.error("Schema init failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);
    // inspect cause for the failing SQL statement before retrying
}

Prevention

When it happens

Trigger: Calling initSchema when sqlScriptRunner.execute() fails: the classpath resource sql/dolphinscheduler_<db>.sql is missing, the DB connection fails mid-script, a statement errors (object already exists, insufficient privileges, unsupported SQL for the dialect), or the script partially applied then failed.

Common situations: Running init-schema on a database that already has DolphinScheduler tables (duplicate table errors); missing sql files in the packaged jar; DB user lacking CREATE privileges; using a database type whose SQL file is incompatible or absent.

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

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