{"record":{"id":"5c7e18e04527b232","repo":"apache/dolphinscheduler","slug":"the-version-table-does-not-exist","errorCode":null,"errorMessage":"The version table does not exist","messagePattern":"The version table does not exist","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java","lineNumber":109,"sourceCode":"\n    private void upgradeDolphinSchedulerDML(String schemaDir, String scriptFile) {\n        String schemaVersion = schemaDir.split(\"_\")[0];\n        String sqlFilePath =\n                String.format(\"sql/upgrade/%s/%s/%s\", schemaDir, dbType.getDb(), scriptFile);\n        try {\n            // Execute the upgraded dolphinscheduler dml\n            SqlScriptRunner sqlScriptRunner = new SqlScriptRunner(dataSource, sqlFilePath);\n            sqlScriptRunner.execute();\n            try (Connection connection = dataSource.getConnection()) {\n                String upgradeSQL;\n                if (databaseDialect.tableExists(T_VERSION_NAME)) {\n                    // Change version in the version table to the new version\n                    upgradeSQL = String.format(\"update %s set version = ?\", T_VERSION_NAME);\n                } else if (databaseDialect.tableExists(T_NEW_VERSION_NAME)) {\n                    // Change version in the version table to the new version\n                    upgradeSQL = String.format(\"update %s set version = ?\", T_NEW_VERSION_NAME);\n                } else {\n                    throw new RuntimeException(\"The version table does not exist\");\n                }\n                try (PreparedStatement pstmt = connection.prepareStatement(upgradeSQL)) {\n                    pstmt.setString(1, schemaVersion);\n                    pstmt.executeUpdate();\n                }\n            }\n            log.info(\"Success execute the dml file, schemaDir:  {}, ddlScript: {}\", schemaDir, scriptFile);\n        } catch (FileNotFoundException e) {\n            log.error(\"Cannot find the DDL file, schemaDir:  {}, ddlScript: {}\", schemaDir, scriptFile, e);\n            throw new RuntimeException(\"sql file not found \", e);\n        } catch (Exception e) {\n            log.error(\"Execute ddl file failed, meet an unknown exception, schemaDir:  {}, ddlScript: {}\", schemaDir,\n                    scriptFile, e);\n            throw new RuntimeException(\"Execute ddl file failed, meet an unknown exception\", e);\n        }\n    }\n\n    /**","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java#L91-L127","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify you are connected to the correct initialized database containing t_ds_version (SHOW TABLES / \\dt).","Run init-schema first if the database is empty, then re-run upgrade.","Recreate the version table and insert the current version row if it was dropped accidentally.","Check the DB user's schema/search_path so the table is visible to the connection."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"java.sql.DatabaseMetaData md = connection.getMetaData();\ntry (ResultSet rs = md.getTables(null, null, \"t_ds_version\", null)) {\n    if (!rs.next()) throw new IllegalStateException(\"Version table missing; cannot run DML upgrade\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    manager.upgradeDolphinScheduler();\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"The version table does not exist\")) {\n        log.error(\"Wrong DB or uninitialized schema - verify JDBC URL and run init-schema first\");\n    } else throw e;\n}","preventionTips":["Verify t_ds_version exists before starting any upgrade.","Never point the upgrade tool at a fresh or wrong database.","Back up the version table before upgrading.","Keep schema/search_path consistent between init and upgrade runs."],"tags":["database","upgrade","version-table"],"backgroundTag":"entity-not-found","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"}