{"record":{"id":"18f93276fb8673ae","repo":"apache/dolphinscheduler","slug":"query-t-ds-process-instance-error","errorCode":null,"errorMessage":"Query t_ds_process_instance error","messagePattern":"Query t_ds_process_instance error","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/v320/V320DolphinSchedulerUpgrader.java","lineNumber":141,"sourceCode":"        }\n    }\n\n    private List<Map<String, Object>> getTaskInstanceWhichProjectCodeIsNull() {\n        List<Map<String, Object>> processInstanceList = new ArrayList<>();\n        try (\n                Connection connection = dataSource.getConnection();\n                PreparedStatement preparedStatement = connection.prepareStatement(\n                        \"select id, process_instance_id from t_ds_task_instance where project_code is null limit 1000\");\n                ResultSet resultSet = preparedStatement.executeQuery()) {\n            while (resultSet.next()) {\n                Map<String, Object> row = new HashMap<>();\n                row.put(\"id\", resultSet.getInt(\"id\"));\n                row.put(\"process_instance_id\", resultSet.getInt(\"process_instance_id\"));\n                processInstanceList.add(row);\n            }\n            return processInstanceList;\n        } catch (Exception ex) {\n            throw new RuntimeException(\"Query t_ds_process_instance error\", ex);\n        }\n\n    }\n\n    private Map<Integer, String> getUserMap() {\n        Map<Integer, String> userMap = new HashMap<>();\n        try (\n                Connection connection = dataSource.getConnection();\n                PreparedStatement preparedStatement =\n                        connection.prepareStatement(\"select id, user_name from t_ds_user\");\n                ResultSet resultSet = preparedStatement.executeQuery()) {\n            while (resultSet.next()) {\n                userMap.put(resultSet.getInt(\"id\"), resultSet.getString(\"user_name\"));\n            }\n        } catch (Exception ex) {\n            throw new RuntimeException(\"Query t_ds_user error\", ex);\n        }\n        return userMap;","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/v320/V320DolphinSchedulerUpgrader.java#L123-L159","documentation":"This RuntimeException is thrown by V320DolphinSchedulerUpgrader.getTaskInstanceWhichProjectCodeIsNull when the JDBC query against t_ds_process_instance fails during the 3.2.0 schema upgrade. The upgrade tool wraps any SQLException/connection failure in this generic RuntimeException with the original exception as cause. It indicates the upgrade cannot read process instance rows that need project_code backfill.","triggerScenarios":"Calling taskInstances/upgrader upgrade from 3.2.0 when the t_ds_process_instance table is missing, locked, corrupted, or the DataSource credentials/URL are wrong; any Exception inside the try-with-resources JDBC block.","commonSituations":"Upgrading a production metadata DB where the user lacks SELECT privilege on t_ds_process_instance; DB was partially upgraded or table renamed; database down or network/firewall issue; driver mismatch causing executeQuery failure.","solutions":["Check the 'Caused by' exception in the stack trace for the real JDBC error","Verify DB connectivity and credentials in the datasource config used by the upgrade tool","Confirm t_ds_process_instance exists and the upgrading DB user has SELECT permission on it","Fix table corruption/locks, then re-run the upgrade","Restore the metadata DB from backup if the schema is inconsistent"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before running the upgrader\ntry (Connection c = dataSource.getConnection();\n     PreparedStatement ps = c.prepareStatement(\"select id from t_ds_process_instance where 1=0\")) {\n    ps.executeQuery();\n} catch (SQLException e) {\n    throw new IllegalStateException(\"t_ds_process_instance not queryable: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    upgrader.upgrade();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Query t_ds_process_instance error\")) {\n        log.error(\"Upgrade failed reading process instances; cause: {}\", e.getCause(), e);\n        // inspect e.getCause() (SQLException) and fix DB access/schema before retry\n    } else { throw e; }\n}","preventionTips":["Always run upgrade tooling against a tested DB backup","Verify DB credentials and SELECT privileges before upgrading","Confirm the source version schema matches the upgrader's expectations","Run upgrades during a maintenance window with the app stopped"],"tags":["database","jdbc","upgrade","sql"],"backgroundTag":"database-query-failed","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"}