apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINITION_NOT_EXIST

WORKFLOW_DEFINITION_NOT_EXIST

Error message

WORKFLOW_DEFINITION_NOT_EXIST: workflow definition not found

What it means

Thrown by queryTaskDefinitionList (and similar by-code lookups) when no workflow definition with the given code exists, or the one found belongs to a different project than the projectCode path parameter. The caller asked for task definitions of a workflow that is not visible in the given project.

Source

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

    /**
     * get task node details based on workflow definition
     *
     * @param loginUser   loginUser
     * @param projectCode project code
     * @param code        workflow definition code
     * @return task node list
     */
    @Override
    public List<TaskDefinition> getTaskNodeListByDefinitionCode(User loginUser, long projectCode, long code) {
        Project project = projectDao.queryByCode(projectCode);
        // check user access for project
        projectService.checkProjectAndAuthThrowException(loginUser, project, null);

        WorkflowDefinition workflowDefinition = workflowDefinitionDao.queryByCode(code).orElse(null);
        if (workflowDefinition == null || projectCode != workflowDefinition.getProjectCode()) {
            log.error("workflow definition does not exist, workflowDefinitionCode:{}.", code);
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_EXIST, String.valueOf(code));
        }
        DagData dagData = processService.genDagData(workflowDefinition);
        return dagData.getTaskDefinitionList();
    }

    /**
     * get task node details map based on workflow definition
     *
     * @param loginUser   loginUser
     * @param projectCode project code
     * @param codes       define codes
     * @return task node list
     */
    @Override
    public Map<Long, List<TaskDefinition>> getNodeListMapByDefinitionCodes(User loginUser, long projectCode,
                                                                           String codes) {
        Project project = projectDao.queryByCode(projectCode);
        // check user access for project

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the workflow code exists via the workflow definition list API for that project and use the correct code.
  2. Ensure the projectCode in the URL matches the project that actually owns the workflow.
  3. Re-create the workflow if it was deleted, or point the request at an existing one.
  4. Confirm the logged-in user targets the right project (codes are unique across projects, but the URL binds them).

Example fix

// before
curl .../projects/123/workflow/definition/9999/tasks   // 9999 not in project 123
// after
curl .../projects/123/workflow/definition/4860899582432/tasks  // code verified via list API
Defensive patterns

Strategy: validation

Validate before calling

Optional<WorkflowDefinition> wf = workflowDefinitionDao.queryByCode(code);
if (wf.isEmpty() || wf.get().getProjectCode() != projectCode) {
    throw new IllegalArgumentException("workflow " + code + " not in project " + projectCode);
}

Try / catch

try {
    taskDefs = client.queryTaskDefinitionList(projectCode, code);
} catch (ServiceException e) {
    if (e.getCode() == Status.WORKFLOW_DEFINITION_NOT_EXIST.getCode()) {
        // refresh workflow list and correct the code
    } else throw e;
}

Prevention

When it happens

Trigger: GET /projects/{projectCode}/workflow/definition/{code}/tasks where code is wrong/deleted, or code exists but workflowDefinition.getProjectCode() != projectCode in the URL.

Common situations: Stale client caches after workflow deletion; using a workflow code copied from another project; typos in code/projectCode path segments; environments synced partially between instances.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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