apache/dolphinscheduler · error · ServiceException

SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR

Q: What causes "SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR: switch workflow definition version error" in apache/dolphinscheduler?

Retry the version switch; transient races or DB hiccups usually clear on a second attempt.

SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR

Error message

SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR: switch workflow definition version error

What it means

Thrown by switchWorkflowDefinitionVersion when processService.switchVersion returns <= 0, meaning the DB update that points the workflow definition at the requested version affected no rows. The existence checks passed, but the actual switch failed — typically a concurrent modification, the definition being updated to the same state, or a datasource failure during the update.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkflowDefinitionServiceImpl.java:1626

                        workflowDefinitionLog.getVersion());
        List<TaskCodeVersionDto> taskDefinitionList = getTaskCodeVersionDtos(workflowTaskRelationList);
        List<TaskDefinitionLog> taskDefinitionLogList =
                taskDefinitionLogMapper.queryByTaskDefinitions(taskDefinitionList.stream()
                        .flatMap(taskCodeVersionDto -> {
                            TaskDefinitionLog taskDefinitionLog = new TaskDefinitionLog();
                            taskDefinitionLog.setCode(taskCodeVersionDto.getCode());
                            taskDefinitionLog.setVersion(taskCodeVersionDto.getVersion());
                            return Stream.of(taskDefinitionLog);
                        }).collect(Collectors.toList()));
        taskDatasourcePermissionChecker.checkPermission(loginUser, taskDefinitionLogList);
        taskSubWorkflowPermissionChecker.checkPermission(loginUser, taskDefinitionLogList);

        int switchVersion = processService.switchVersion(workflowDefinition, workflowDefinitionLog);
        if (switchVersion <= 0) {
            log.error(
                    "Switch workflow definition version error, projectCode:{}, workflowDefinitionCode:{}, version:{}.",
                    projectCode, code, version);
            throw new ServiceException(Status.SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR);
        }

        saveWorkflowLineage(workflowDefinitionLog.getProjectCode(), workflowDefinitionLog.getCode(),
                workflowDefinitionLog.getVersion(), taskDefinitionLogList);

        log.info("Switch workflow definition version complete, projectCode:{}, workflowDefinitionCode:{}, version:{}.",
                projectCode, code, version);
    }

    private static @NotNull List<TaskCodeVersionDto> getTaskCodeVersionDtos(List<WorkflowTaskRelation> workflowTaskRelationList) {
        List<TaskCodeVersionDto> taskDefinitionList = new ArrayList<>();
        for (WorkflowTaskRelation workflowTaskRelation : workflowTaskRelationList) {
            if (workflowTaskRelation.getPreTaskCode() != 0) {
                TaskCodeVersionDto taskCodeVersionDto = new TaskCodeVersionDto();
                taskCodeVersionDto.setCode(workflowTaskRelation.getPreTaskCode());
                taskCodeVersionDto.setVersion(workflowTaskRelation.getPreTaskVersion());
                taskDefinitionList.add(taskCodeVersionDto);
            }

View on GitHub (pinned to 02eac45a1b)

Solutions

Retry the version switch; transient races or DB hiccups usually clear on a second attempt.
Verify the workflow still exists and its current version (GET .../workflow-definition/{code}) — if it was deleted concurrently, re-check error 435 first.
Coordinate edits: ensure no other user/process is modifying the same workflow at the same time.
Check API server logs and the metadata DB for the underlying update failure (locks, deadlocks, connection errors).

Example fix

// before: single blind call
switchWorkflowDefinitionVersion(user, projectCode, code, version);
// after: serialize edits & retry
synchronized (workflowLock(code)) { // or use optimistic re-read
  if (exists(code, projectCode)) switchWorkflowDefinitionVersion(user, projectCode, code, version);
}

Defensive patterns

Strategy: retry

Validate before calling

// Re-check the definition right before switching to reduce race window
WorkflowDefinition wf = workflowDefinitionDao.queryByCode(code).orElse(null);
if (wf == null || wf.getProjectCode() != projectCode) throw new IllegalStateException("workflow gone");

Try / catch

try {
    workflowDefinitionService.switchWorkflowDefinitionVersion(user, projectCode, code, version);
} catch (ServiceException e) {
    if (e.getCode() == Status.SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR) {
        // re-read definition, ensure it still exists, wait, and retry
    }
}

Prevention

Avoid concurrent edits/switches on the same workflow — coordinate users and automation.
Retry once on failure; the underlying update is transactional and transient DB issues self-heal.
Watch for deadlocks/locks on t_ds_workflow_definition in DB monitoring.

When it happens

Trigger: switchWorkflowDefinitionVersion racing with another edit of the same workflow (the target definition row changed or was deleted between checks and update), or processService.switchVersion's update affecting 0 rows due to a DB issue.

Common situations: Two users/scripts switching or editing the same workflow simultaneously; transaction rollback in the underlying update; DB connectivity failures during the write.

Related errors

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