apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINE_STATE_ONLINE

WORKFLOW_DEFINE_STATE_ONLINE

Error message

Task definition version can not be switched due to workflow definition is {}, taskDefinitionCode:{}.

What it means

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.

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.

Example fix

// before
taskDefinitionService.switchVersion(loginUser, projectCode, taskCode, 3); // fails: task online
// after
// offline the workflow first via UI/API, then:
taskDefinitionService.switchVersion(loginUser, projectCode, taskCode, 3);

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the task is not online before switching
// e.g. via UI, or check workflow release state containing the task

Try / catch

try {
    taskDefinitionService.switchVersion(loginUser, projectCode, taskCode, version);
} catch (ServiceException e) {
    if (e.getCode() == Status.WORKFLOW_DEFINE_STATE_ONLINE) {
        // offline the workflow, retry switch, then re-online
    } else { throw e; }
}

Prevention

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.

When it happens

Trigger: POST /task-definition/{projectCode}/{taskCode}/switch-version (switchVersion) on a taskCode that has online task instances/definitions.

Common situations: Rolling back a task to a prior version while its workflow is still published; CI automation that switches versions without first offlining the workflow.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/TaskDefinitionServiceImpl.java:201

        return taskDefinition;
    }

    /**
     * switch task definition
     *
     * @param loginUser   login user
     * @param projectCode project code
     * @param taskCode    task code
     * @param version     the version user want to switch
     */
    @Transactional
    @Override
    public void switchVersion(User loginUser, long projectCode, long taskCode, int version) {
        Project project = projectDao.queryByCode(projectCode);
        projectService.checkHasProjectWritePermissionThrowException(loginUser, project);

        if (processService.isTaskOnline(taskCode)) {
            log.warn(
                    "Task definition version can not be switched due to workflow definition is {}, taskDefinitionCode:{}.",
                    ReleaseState.ONLINE.getDescp(), taskCode);
            throw new ServiceException(Status.WORKFLOW_DEFINE_STATE_ONLINE);
        }
        TaskDefinition taskDefinition = taskDefinitionDao.queryByCode(taskCode);
        if (taskDefinition == null || projectCode != taskDefinition.getProjectCode()) {
            log.error("Task definition does not exist, taskDefinitionCode:{}.", taskCode);
            throw new ServiceException(Status.TASK_DEFINE_NOT_EXIST, String.valueOf(taskCode));
        }
        TaskDefinitionLog taskDefinitionUpdate =
                taskDefinitionLogMapper.queryByDefinitionCodeAndVersion(taskCode, version);
        taskDatasourcePermissionChecker.checkPermission(loginUser, Collections.singletonList(taskDefinitionUpdate));
        taskSubWorkflowPermissionChecker.checkPermission(loginUser, Collections.singletonList(taskDefinitionUpdate));
        taskDefinitionUpdate.setUserId(loginUser.getId());
        taskDefinitionUpdate.setUpdateTime(new Date());
        taskDefinitionUpdate.setId(taskDefinition.getId());
        boolean switchSuccess = taskDefinitionDao.updateById(taskDefinitionUpdate);
        if (!switchSuccess) {

View on GitHub (pinned to 02eac45a1b)