What causes "Upgrade version error, sql: " in apache/dolphinscheduler?

Grant UPDATE on t_ds_version to the upgrade DB user, then re-run the version update.

apache/dolphinscheduler · error · RuntimeException

Upgrade version error, sql:

Error message

Upgrade version error, sql:

What it means

UpgradeDao.updateVersion executes 'update <t_ds_version> set version = ?' to stamp the new schema version. A SQLException is rethrown as RuntimeException 'Upgrade version error, sql: <sql>'. The DDL/DML upgrades succeeded but recording the new version failed, leaving the recorded version stale.

Source

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

     *
     * @param version version
     */
    public void updateVersion(String version) {
        // Change version in the version table to the new version
        String versionName = T_VERSION_NAME;
        if (!SchemaUtils.isAGreatVersion("1.2.0", version)) {
            versionName = "t_ds_version";
        }
        String upgradeSQL = String.format("update %s set version = ?", versionName);
        try (
                Connection conn = dataSource.getConnection();
                PreparedStatement pstmt = conn.prepareStatement(upgradeSQL)) {
            pstmt.setString(1, version);
            pstmt.executeUpdate();

        } catch (SQLException e) {
            log.error("Update version error, sql: {}", upgradeSQL, e);
            throw new RuntimeException("Upgrade version error, sql: " + upgradeSQL, e);
        }
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

Grant UPDATE on t_ds_version to the upgrade DB user, then re-run the version update.
Verify a row exists in t_ds_version; insert one with the current version if the table is empty.
Check DB connectivity/timeouts and re-run the upgrade (DDL/DML are typically idempotent-guarded by version checks).
Ensure you are not connected to a read-only replica; point at the primary database.

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: version table has an updatable row and user has UPDATE privilege
try (Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("select count(*) from t_ds_version")) {
    rs.next();
    if (rs.getInt(1) == 0) throw new IllegalStateException("t_ds_version is empty; insert current version row first");
}

Try / catch

try {
    manager.upgradeDolphinScheduler();
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Upgrade version error")) {
        log.error("Version stamp update failed (privileges/readonly DB): {}",
                e.getCause() != null ? e.getCause().getMessage() : null, e);
        // fix privileges, then manually: UPDATE t_ds_version SET version='<new>';
    } else throw e;
}

Prevention

Run upgrades with an account holding UPDATE on t_ds_version.
Never run upgrades against read-only replicas.
Ensure t_ds_version contains a version row before upgrading.
After an upgrade, verify SELECT version FROM t_ds_version matches the target version.

When it happens

Trigger: Calling updateVersion when the UPDATE throws SQLException: missing UPDATE privilege on t_ds_version, connection dropped during the upgrade, the version table exists but the version row is missing/locked, or read-only replica connection.

Common situations: Upgrade run with a read-only or low-privilege DB account; connection timeouts during long upgrades; version table empty (no row to update); DB in read-only/replica mode.

Related errors

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