apache/dolphinscheduler · error · RuntimeException

Query t_ds_process_instance error

Error message

Query t_ds_process_instance error

What it means

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.

Source

Thrown at dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/v320/V320DolphinSchedulerUpgrader.java:141

        }
    }

    private List<Map<String, Object>> getTaskInstanceWhichProjectCodeIsNull() {
        List<Map<String, Object>> processInstanceList = new ArrayList<>();
        try (
                Connection connection = dataSource.getConnection();
                PreparedStatement preparedStatement = connection.prepareStatement(
                        "select id, process_instance_id from t_ds_task_instance where project_code is null limit 1000");
                ResultSet resultSet = preparedStatement.executeQuery()) {
            while (resultSet.next()) {
                Map<String, Object> row = new HashMap<>();
                row.put("id", resultSet.getInt("id"));
                row.put("process_instance_id", resultSet.getInt("process_instance_id"));
                processInstanceList.add(row);
            }
            return processInstanceList;
        } catch (Exception ex) {
            throw new RuntimeException("Query t_ds_process_instance error", ex);
        }

    }

    private Map<Integer, String> getUserMap() {
        Map<Integer, String> userMap = new HashMap<>();
        try (
                Connection connection = dataSource.getConnection();
                PreparedStatement preparedStatement =
                        connection.prepareStatement("select id, user_name from t_ds_user");
                ResultSet resultSet = preparedStatement.executeQuery()) {
            while (resultSet.next()) {
                userMap.put(resultSet.getInt("id"), resultSet.getString("user_name"));
            }
        } catch (Exception ex) {
            throw new RuntimeException("Query t_ds_user error", ex);
        }
        return userMap;

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check the 'Caused by' exception in the stack trace for the real JDBC error
2. Verify DB connectivity and credentials in the datasource config used by the upgrade tool
3. Confirm t_ds_process_instance exists and the upgrading DB user has SELECT permission on it
4. Fix table corruption/locks, then re-run the upgrade
5. Restore the metadata DB from backup if the schema is inconsistent

// before running the upgrader
try (Connection c = dataSource.getConnection();
     PreparedStatement ps = c.prepareStatement("select id from t_ds_process_instance where 1=0")) {
    ps.executeQuery();
} catch (SQLException e) {
    throw new IllegalStateException("t_ds_process_instance not queryable: " + e.getMessage(), e);
}

try {
    upgrader.upgrade();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Query t_ds_process_instance error")) {
        log.error("Upgrade failed reading process instances; cause: {}", e.getCause(), e);
        // inspect e.getCause() (SQLException) and fix DB access/schema before retry
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Query t_ds_user error
• Query t_ds_process_definition_log error
• Query t_ds_schedules error
• Update t_ds_process_instance error
• Execute ddl file failed, meet an unknown exception

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