{"record":{"id":"cc203fe3959d12d9","repo":"apache/dolphinscheduler","slug":"execute-ddl-file-failed-meet-an-unknown-exception","errorCode":null,"errorMessage":"Execute ddl file failed, meet an unknown exception","messagePattern":"Execute ddl file failed, meet an unknown exception","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java","lineNumber":123,"sourceCode":"                } 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    /**\n     * upgradeDolphinScheduler DDL\n     *\n     * @param schemaDir schemaDir\n     */\n    public void upgradeDolphinSchedulerDDL(String schemaDir, String scriptFile) {\n        String sqlFilePath =\n                String.format(\"sql/upgrade/%s/%s/%s\", schemaDir, dbType.getDb(), scriptFile);\n        SqlScriptRunner sqlScriptRunner = new SqlScriptRunner(dataSource, sqlFilePath);\n        try {\n            // Execute the dolphinscheduler ddl.sql for the upgrade\n            sqlScriptRunner.execute();\n            log.info(\"Success execute the ddl file, schemaDir:  {}, ddlScript: {}\", schemaDir, scriptFile);\n        } catch (FileNotFoundException e) {\n            log.error(\"Cannot find the DDL file, schemaDir:  {}, ddlScript: {}\", schemaDir, scriptFile, e);","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java#L105-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the cause stack trace to find the failing SQL statement in the DML file and fix the data or statement.","Restore the database from backup and re-run the upgrade after fixing the issue.","Grant the upgrade user UPDATE/INSERT/DELETE privileges on all t_ds_* tables.","Check for prior partial upgrade artifacts (duplicate rows/constraints) and clean them up."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-flight: backup DB and confirm privileges\n// GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema> TO upgrade_user;\n// restore from backup if a previous upgrade partially applied","typeGuard":null,"tryCatchPattern":"try {\n    manager.upgradeDolphinScheduler();\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"unknown exception\")) {\n        log.error(\"DML upgrade failed; cause: {} - fix failing statement, restore backup, retry\",\n                e.getCause() != null ? e.getCause().getMessage() : null, e);\n    } else throw e;\n}","preventionTips":["Always back up the database before running upgrades.","Test the upgrade against a restored copy of production first.","Grant full DML privileges to the upgrade user.","Resolve leftover artifacts from previously failed upgrades."],"tags":["database","upgrade","sql"],"backgroundTag":"sql-query-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}