apache/dolphinscheduler · error · RuntimeException

The version table does not exist

Error message

The version table does not exist

What it means

During DML upgrade, UpgradeDao looks for the version table (T_VERSION_NAME, then T_NEW_VERSION_NAME) to UPDATE its version column. If neither table exists it throws RuntimeException 'The version table does not exist'. This is a guard so the upgrade never proceeds without a place to record the new schema version.

Source

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

    private void upgradeDolphinSchedulerDML(String schemaDir, String scriptFile) {
        String schemaVersion = schemaDir.split("_")[0];
        String sqlFilePath =
                String.format("sql/upgrade/%s/%s/%s", schemaDir, dbType.getDb(), scriptFile);
        try {
            // Execute the upgraded dolphinscheduler dml
            SqlScriptRunner sqlScriptRunner = new SqlScriptRunner(dataSource, sqlFilePath);
            sqlScriptRunner.execute();
            try (Connection connection = dataSource.getConnection()) {
                String upgradeSQL;
                if (databaseDialect.tableExists(T_VERSION_NAME)) {
                    // Change version in the version table to the new version
                    upgradeSQL = String.format("update %s set version = ?", T_VERSION_NAME);
                } 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);
        }
    }

    /**

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify you are connected to the correct initialized database containing t_ds_version (SHOW TABLES / \dt).
2. Run init-schema first if the database is empty, then re-run upgrade.
3. Recreate the version table and insert the current version row if it was dropped accidentally.
4. Check the DB user's schema/search_path so the table is visible to the connection.

java.sql.DatabaseMetaData md = connection.getMetaData();
try (ResultSet rs = md.getTables(null, null, "t_ds_version", null)) {
    if (!rs.next()) throw new IllegalStateException("Version table missing; cannot run DML upgrade");
}

try {
    manager.upgradeDolphinScheduler();
} catch (RuntimeException e) {
    if (e.getMessage().contains("The version table does not exist")) {
        log.error("Wrong DB or uninitialized schema - verify JDBC URL and run init-schema first");
    } else throw e;
}

When it happens

Trigger: Running upgradeDolphinSchedulerDML against a database where neither t_ds_version nor the alternate new version table exists — fresh database, upgrade ran against wrong schema, or the table was renamed/dropped.

Common situations: Pointing the upgrade tool at the wrong database or schema; upgrading a DB that was never initialized; manual cleanup dropped the version table; different DolphinScheduler versions using different version-table names.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Unable to determine current software version, so cannot upgr
• sql file not found
• Execute ddl file failed, meet an unknown exception
• Upgrade version error, sql:
• Query t_ds_process_instance error

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