{"record":{"id":"6602830ab83b3f4d","repo":"apache/dolphinscheduler","slug":"switch-workflow-definition-version-error","errorCode":"SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR","errorMessage":"SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR: switch workflow definition version error","messagePattern":"SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR: switch workflow definition version error","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkflowDefinitionServiceImpl.java","lineNumber":1626,"sourceCode":"                        workflowDefinitionLog.getVersion());\n        List<TaskCodeVersionDto> taskDefinitionList = getTaskCodeVersionDtos(workflowTaskRelationList);\n        List<TaskDefinitionLog> taskDefinitionLogList =\n                taskDefinitionLogMapper.queryByTaskDefinitions(taskDefinitionList.stream()\n                        .flatMap(taskCodeVersionDto -> {\n                            TaskDefinitionLog taskDefinitionLog = new TaskDefinitionLog();\n                            taskDefinitionLog.setCode(taskCodeVersionDto.getCode());\n                            taskDefinitionLog.setVersion(taskCodeVersionDto.getVersion());\n                            return Stream.of(taskDefinitionLog);\n                        }).collect(Collectors.toList()));\n        taskDatasourcePermissionChecker.checkPermission(loginUser, taskDefinitionLogList);\n        taskSubWorkflowPermissionChecker.checkPermission(loginUser, taskDefinitionLogList);\n\n        int switchVersion = processService.switchVersion(workflowDefinition, workflowDefinitionLog);\n        if (switchVersion <= 0) {\n            log.error(\n                    \"Switch workflow definition version error, projectCode:{}, workflowDefinitionCode:{}, version:{}.\",\n                    projectCode, code, version);\n            throw new ServiceException(Status.SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR);\n        }\n\n        saveWorkflowLineage(workflowDefinitionLog.getProjectCode(), workflowDefinitionLog.getCode(),\n                workflowDefinitionLog.getVersion(), taskDefinitionLogList);\n\n        log.info(\"Switch workflow definition version complete, projectCode:{}, workflowDefinitionCode:{}, version:{}.\",\n                projectCode, code, version);\n    }\n\n    private static @NotNull List<TaskCodeVersionDto> getTaskCodeVersionDtos(List<WorkflowTaskRelation> workflowTaskRelationList) {\n        List<TaskCodeVersionDto> taskDefinitionList = new ArrayList<>();\n        for (WorkflowTaskRelation workflowTaskRelation : workflowTaskRelationList) {\n            if (workflowTaskRelation.getPreTaskCode() != 0) {\n                TaskCodeVersionDto taskCodeVersionDto = new TaskCodeVersionDto();\n                taskCodeVersionDto.setCode(workflowTaskRelation.getPreTaskCode());\n                taskCodeVersionDto.setVersion(workflowTaskRelation.getPreTaskVersion());\n                taskDefinitionList.add(taskCodeVersionDto);\n            }","sourceCodeStart":1608,"sourceCodeEnd":1644,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkflowDefinitionServiceImpl.java#L1608-L1644","documentation":"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.","triggerScenarios":"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.","commonSituations":"Two users/scripts switching or editing the same workflow simultaneously; transaction rollback in the underlying update; DB connectivity failures during the write.","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)."],"exampleFix":"// before: single blind call\nswitchWorkflowDefinitionVersion(user, projectCode, code, version);\n// after: serialize edits & retry\nsynchronized (workflowLock(code)) { // or use optimistic re-read\n  if (exists(code, projectCode)) switchWorkflowDefinitionVersion(user, projectCode, code, version);\n}","handlingStrategy":"retry","validationCode":"// Re-check the definition right before switching to reduce race window\nWorkflowDefinition wf = workflowDefinitionDao.queryByCode(code).orElse(null);\nif (wf == null || wf.getProjectCode() != projectCode) throw new IllegalStateException(\"workflow gone\");","typeGuard":null,"tryCatchPattern":"try {\n    workflowDefinitionService.switchWorkflowDefinitionVersion(user, projectCode, code, version);\n} catch (ServiceException e) {\n    if (e.getCode() == Status.SWITCH_WORKFLOW_DEFINITION_VERSION_ERROR) {\n        // re-read definition, ensure it still exists, wait, and retry\n    }\n}","preventionTips":["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."],"tags":["workflow-version","concurrency","database","transaction"],"backgroundTag":"database-write-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"}