{"record":{"id":"f5553d672fad4ca1","repo":"apache/dolphinscheduler","slug":"workflow-define-state-online-f5553d","errorCode":"WORKFLOW_DEFINE_STATE_ONLINE","errorMessage":"Task definition version can not be switched due to workflow definition is {}, taskDefinitionCode:{}.","messagePattern":"Task definition version can not be switched due to workflow definition is (.+?), taskDefinitionCode:(.+?)\\.","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/TaskDefinitionServiceImpl.java","lineNumber":201,"sourceCode":"        return taskDefinition;\n    }\n\n    /**\n     * switch task definition\n     *\n     * @param loginUser   login user\n     * @param projectCode project code\n     * @param taskCode    task code\n     * @param version     the version user want to switch\n     */\n    @Transactional\n    @Override\n    public void switchVersion(User loginUser, long projectCode, long taskCode, int version) {\n        Project project = projectDao.queryByCode(projectCode);\n        projectService.checkHasProjectWritePermissionThrowException(loginUser, project);\n\n        if (processService.isTaskOnline(taskCode)) {\n            log.warn(\n                    \"Task definition version can not be switched due to workflow definition is {}, taskDefinitionCode:{}.\",\n                    ReleaseState.ONLINE.getDescp(), taskCode);\n            throw new ServiceException(Status.WORKFLOW_DEFINE_STATE_ONLINE);\n        }\n        TaskDefinition taskDefinition = taskDefinitionDao.queryByCode(taskCode);\n        if (taskDefinition == null || projectCode != taskDefinition.getProjectCode()) {\n            log.error(\"Task definition does not exist, taskDefinitionCode:{}.\", taskCode);\n            throw new ServiceException(Status.TASK_DEFINE_NOT_EXIST, String.valueOf(taskCode));\n        }\n        TaskDefinitionLog taskDefinitionUpdate =\n                taskDefinitionLogMapper.queryByDefinitionCodeAndVersion(taskCode, version);\n        taskDatasourcePermissionChecker.checkPermission(loginUser, Collections.singletonList(taskDefinitionUpdate));\n        taskSubWorkflowPermissionChecker.checkPermission(loginUser, Collections.singletonList(taskDefinitionUpdate));\n        taskDefinitionUpdate.setUserId(loginUser.getId());\n        taskDefinitionUpdate.setUpdateTime(new Date());\n        taskDefinitionUpdate.setId(taskDefinition.getId());\n        boolean switchSuccess = taskDefinitionDao.updateById(taskDefinitionUpdate);\n        if (!switchSuccess) {","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/TaskDefinitionServiceImpl.java#L183-L219","documentation":"Thrown by TaskDefinitionServiceImpl.switchVersion when trying to switch a task definition's version while the task is online (processService.isTaskOnline(taskCode) is true). Online tasks are part of running/installed workflow definitions and cannot have their version changed. Note the message reuses Status.WORKFLOW_DEFINE_STATE_ONLINE.","triggerScenarios":"POST /task-definition/{projectCode}/{taskCode}/switch-version (switchVersion) on a taskCode that has online task instances/definitions.","commonSituations":"Rolling back a task to a prior version while its workflow is still published; CI automation that switches versions without first offlining the workflow.","solutions":["Take the containing workflow definition offline (release state OFFLINE) so the task is no longer online, then retry switchVersion.","Query the task's online state (processService.isTaskOnline / task-definition API) before switching in automation.","Clone/edit the task in a draft workflow instead of switching versions of a live task."],"exampleFix":"// before\ntaskDefinitionService.switchVersion(loginUser, projectCode, taskCode, 3); // fails: task online\n// after\n// offline the workflow first via UI/API, then:\ntaskDefinitionService.switchVersion(loginUser, projectCode, taskCode, 3);","handlingStrategy":"try-catch","validationCode":"// ensure the task is not online before switching\n// e.g. via UI, or check workflow release state containing the task","typeGuard":null,"tryCatchPattern":"try {\n    taskDefinitionService.switchVersion(loginUser, projectCode, taskCode, version);\n} catch (ServiceException e) {\n    if (e.getCode() == Status.WORKFLOW_DEFINE_STATE_ONLINE) {\n        // offline the workflow, retry switch, then re-online\n    } else { throw e; }\n}","preventionTips":["Offline the owning workflow before any task version switch.","Check task online state in CI before automated rollbacks.","Coordinate version switches with change-management windows."],"tags":["task-definition","release-state","versioning"],"backgroundTag":"invalid-state-transition","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"}