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.

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)

Solutions

  1. Take the containing workflow definition offline (release state OFFLINE) so the task is no longer online, then retry switchVersion.
  2. Query the task's online state (processService.isTaskOnline / task-definition API) before switching in automation.
  3. 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

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.