apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINITION_NOT_EXIST

WORKFLOW_DEFINITION_NOT_EXIST

Error message

WORKFLOW_DEFINITION_NOT_EXIST: workflow definition {workflowDefinitionCode} does not exist

What it means

WORKFLOW_DEFINITION_NOT_EXIST is thrown by projectPermCheckByWorkflowCode (which deleteSchedulesById calls) when workflowDefinitionDao.queryByCode() finds no workflow definition for the given code. This means the schedule points at a workflow that no longer exists, so permission/project checks cannot proceed and the delete is aborted.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/SchedulerServiceImpl.java:203

        scheduleObj.setWorkerGroup(workerGroup);
        scheduleObj.setEnvironmentCode(environmentCode);
        scheduleDao.insert(scheduleObj);

        /**
         * updateWorkflowInstance receivers and cc by workflow definition id
         */
        workflowDefinition.setWarningGroupId(warningGroupId);
        workflowDefinitionDao.updateById(workflowDefinition);

        log.info("Schedule create complete, projectCode:{}, workflowDefinitionCode:{}, scheduleId:{}.",
                projectCode, workflowDefinitionCode, scheduleObj.getId());
        return scheduleDao.queryById(scheduleObj.getId());
    }

    protected void projectPermCheckByWorkflowCode(User loginUser, long workflowDefinitionCode) {
        WorkflowDefinition workflowDefinition = workflowDefinitionDao.queryByCode(workflowDefinitionCode).orElse(null);
        if (workflowDefinition == null) {
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_EXIST, workflowDefinitionCode);
        }
        Project project = projectDao.queryByCode(workflowDefinition.getProjectCode());
        this.projectService.checkHasProjectWritePermissionThrowException(loginUser, project);
    }

    /**
     * updateWorkflowInstance schedule
     *
     * @param loginUser               login user
     * @param projectCode             project code
     * @param id                      scheduler id
     * @param scheduleExpression      scheduler
     * @param warningType             warning type
     * @param warningGroupId          warning group id
     * @param failureStrategy         failure strategy
     * @param workerGroup             worker group
     * @param tenantCode              tenant code
     * @param environmentCode         environment code

View on GitHub (pinned to 02eac45a1b)

Solutions

Confirm the workflow exists: GET /projects/{projectCode}/workflow-definition/{code} or query t_ds_workflow_definition by code.
Delete the orphaned schedule directly or recreate the workflow under the expected code before retrying.
Check the projectCode in the URL matches the project that actually owns the workflow the schedule references.

Example fix

// before
curl -X DELETE '/projects/1/schedules/55'   // workflow behind schedule 55 was deleted
// after
// recreate workflow or remove orphan schedule row, then retry with a valid schedule/workflow pair
curl -X DELETE '/projects/1/schedules/56'

Defensive patterns

Strategy: validation

Validate before calling

WorkflowDefinition wf = workflowDefinitionDao.queryByCode(code).orElse(null);
if (wf == null) {
    throw new IllegalStateException("Workflow " + code + " does not exist; cannot operate on its schedules");
}

Try / catch

try { schedulerService.deleteSchedulesById(user, scheduleId); } catch (ServiceException e) { if (e.getCode() == Status.WORKFLOW_DEFINITION_NOT_EXIST) { /* schedule is orphaned; clean up row or recreate workflow */ } }

Prevention

Delete a workflow's schedules before deleting the workflow
Avoid direct DB manipulation that leaves schedule rows orphaned
Re-derive workflow codes per environment instead of hardcoding them

When it happens

Trigger: DELETE /projects/{projectCode}/schedules/{scheduleId} where the schedule's workflowDefinitionCode references a workflow that was deleted (or whose code is wrong/stale). Since deleteSchedulesById first loads the schedule by id, this fires only when the schedule row survives but its workflow row does not.

Common situations: Orphaned schedule rows left after a workflow was deleted in an older version or via direct DB manipulation; copying schedule definitions across environments where workflow codes differ; using an outdated cached workflow code in automation scripts.

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/fc807cfff4eef499. Report an issue: GitHub.