apache/dolphinscheduler · error · ServiceException

SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_ERROR

SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_ERROR

Error message

SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_ERROR: switch workflow definition version error because workflow definition [{0}] does not exist

What it means

Thrown by switchWorkflowDefinitionVersion when the workflow definition identified by `code` does not exist, or exists but does not belong to the given projectCode. The API cannot switch the version of a workflow it cannot find in the expected project. The workflow code is interpolated into the localized message.

Source

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

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

        WorkflowDefinition workflowDefinition = workflowDefinitionDao.queryByCode(code).orElse(null);
        if (Objects.isNull(workflowDefinition) || projectCode != workflowDefinition.getProjectCode()) {
            log.error(
                    "Switch workflow definition error because it does not exist, projectCode:{}, workflowDefinitionCode:{}.",
                    projectCode, code);
            throw new ServiceException(Status.SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_ERROR,
                    code);
        }

        WorkflowDefinitionLog workflowDefinitionLog =
                workflowDefinitionLogMapper.queryByDefinitionCodeAndVersion(code, version);
        if (Objects.isNull(workflowDefinitionLog)) {
            log.error(
                    "Switch workflow definition error because version does not exist, projectCode:{}, workflowDefinitionCode:{}, version:{}.",
                    projectCode, code, version);
            throw new ServiceException(
                    Status.SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_VERSION_ERROR,
                    workflowDefinition.getCode(), version);
        }
        List<WorkflowTaskRelation> workflowTaskRelationList = workflowTaskRelationDao
                .queryWorkflowTaskRelationsByWorkflowDefinitionCode(workflowDefinitionLog.getCode(),
                        workflowDefinitionLog.getVersion());
        List<TaskCodeVersionDto> taskDefinitionList = getTaskCodeVersionDtos(workflowTaskRelationList);
        List<TaskDefinitionLog> taskDefinitionLogList =

View on GitHub (pinned to 02eac45a1b)

Solutions

Verify the workflow code exists and matches: GET /dolphinscheduler/projects/{projectCode}/workflow-definition/list and compare codes.
Confirm the code belongs to the same projectCode you pass in the URL — project mismatch triggers this error even if the code exists.
If the workflow was deleted, re-create it or pick the correct code; no version switch is possible on a deleted definition.
Refresh your automation's stored workflow codes after re-imports, since new imports get newly generated codes.

Example fix

// before: switchWorkflowDefinitionVersion(user, 42L, 99999999999999L, 3) // code not in project 42
// after: resolve real code first
long code = workflowList.stream().filter(w -> "my_wf".equals(w.getName())).findFirst().get().getCode();
switchWorkflowDefinitionVersion(user, 42L, code, 3);

Defensive patterns

Strategy: validation

Validate before calling

boolean workflowExistsInProject(long projectCode, long code) {
    return workflowDefinitionDao.queryByCode(code)
        .map(wf -> wf.getProjectCode() == projectCode)
        .orElse(false);
}
// call before switchWorkflowDefinitionVersion

Try / catch

try {
    workflowDefinitionService.switchWorkflowDefinitionVersion(user, projectCode, code, version);
} catch (ServiceException e) {
    if (e.getCode() == Status.SWITCH_WORKFLOW_DEFINITION_VERSION_NOT_EXIST_WORKFLOW_DEFINITION_ERROR) {
        // re-list workflows to get the current code / confirm project
    }
}

Prevention

Fetch workflow codes dynamically from the list API instead of hard-coding them.
Never reuse codes across environments — codes are generated per instance.
Confirm projectCode and code together; a code from another project raises this same error.
Handle deleted workflows in automation before attempting version switches.

When it happens

Trigger: Calling POST /dolphinscheduler/projects/{projectCode}/workflow-definition/{code}/version/switch (or switchWorkflowDefinitionVersion) with a stale/wrong workflow code, or a code belonging to a different project than the projectCode path parameter.

Common situations: Using a workflow code copied from another environment (codes are generated per-instance); the workflow was deleted before the switch; passing projectCode/code swapped or mismatched; scripting against the API with an outdated code list.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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