apache/dolphinscheduler · error · RuntimeException

Execute ddl file failed, meet an unknown exception

Error message

Execute ddl file failed, meet an unknown exception

What it means

In UpgradeDao.upgradeDolphinSchedulerDML, any exception other than FileNotFoundException while executing the DML script is rethrown as RuntimeException 'Execute ddl file failed, meet an unknown exception'. It signals an unanticipated failure (SQL error, connection loss) while applying upgrade DML statements.

Source

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

                } else if (databaseDialect.tableExists(T_NEW_VERSION_NAME)) {
                    // Change version in the version table to the new version
                    upgradeSQL = String.format("update %s set version = ?", T_NEW_VERSION_NAME);
                } else {
                    throw new RuntimeException("The version table does not exist");
                }
                try (PreparedStatement pstmt = connection.prepareStatement(upgradeSQL)) {
                    pstmt.setString(1, schemaVersion);
                    pstmt.executeUpdate();
                }
            }
            log.info("Success execute the dml file, schemaDir:  {}, ddlScript: {}", schemaDir, scriptFile);
        } catch (FileNotFoundException e) {
            log.error("Cannot find the DDL file, schemaDir:  {}, ddlScript: {}", schemaDir, scriptFile, e);
            throw new RuntimeException("sql file not found ", e);
        } catch (Exception e) {
            log.error("Execute ddl file failed, meet an unknown exception, schemaDir:  {}, ddlScript: {}", schemaDir,
                    scriptFile, e);
            throw new RuntimeException("Execute ddl file failed, meet an unknown exception", e);
        }
    }

    /**
     * upgradeDolphinScheduler DDL
     *
     * @param schemaDir schemaDir
     */
    public void upgradeDolphinSchedulerDDL(String schemaDir, String scriptFile) {
        String sqlFilePath =
                String.format("sql/upgrade/%s/%s/%s", schemaDir, dbType.getDb(), scriptFile);
        SqlScriptRunner sqlScriptRunner = new SqlScriptRunner(dataSource, sqlFilePath);
        try {
            // Execute the dolphinscheduler ddl.sql for the upgrade
            sqlScriptRunner.execute();
            log.info("Success execute the ddl file, schemaDir:  {}, ddlScript: {}", schemaDir, scriptFile);
        } catch (FileNotFoundException e) {
            log.error("Cannot find the DDL file, schemaDir:  {}, ddlScript: {}", schemaDir, scriptFile, e);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Read the cause stack trace to find the failing SQL statement in the DML file and fix the data or statement.
2. Restore the database from backup and re-run the upgrade after fixing the issue.
3. Grant the upgrade user UPDATE/INSERT/DELETE privileges on all t_ds_* tables.
4. Check for prior partial upgrade artifacts (duplicate rows/constraints) and clean them up.

// pre-flight: backup DB and confirm privileges
// GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema> TO upgrade_user;
// restore from backup if a previous upgrade partially applied

try {
    manager.upgradeDolphinScheduler();
} catch (RuntimeException e) {
    if (e.getMessage().contains("unknown exception")) {
        log.error("DML upgrade failed; cause: {} - fix failing statement, restore backup, retry",
                e.getCause() != null ? e.getCause().getMessage() : null, e);
    } else throw e;
}

When it happens

Trigger: Calling upgradeDolphinSchedulerDML when executing the script raises a non-FileNotFound exception: failing SQL statement in dolphinscheduler_dml.sql, constraint violations from existing data, connection drop mid-script, insufficient DML privileges.

Common situations: Upgrading databases with data that violates new DML assumptions; partial upgrades leaving the DB in a mixed state; DB user lacking UPDATE/INSERT privileges on metadata tables.

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

• Query t_ds_process_instance error
• Query t_ds_user error
• Query t_ds_process_definition_log error
• Query t_ds_schedules error
• Update t_ds_process_instance error

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