apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINITION_NOT_EXIST

WORKFLOW_DEFINITION_NOT_EXIST

Error message

WORKFLOW_DEFINITION_NOT_EXIST

What it means

Thrown by triggerWorkflowDefinition when the workflow definition cannot be loaded for the given code, or when it exists but belongs to a different project than the one in the request URL. The check after triggerWorkflowRequestTransformer.transform ensures the definition is both present and scoped to the URL's project.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/ExecutorServiceImpl.java:133

    @Autowired
    private BackfillWorkflowRequestTransformer backfillWorkflowRequestTransformer;

    @Autowired
    private BackfillWorkflowDTOValidator backfillWorkflowDTOValidator;

    @Autowired
    private ExecutorClient executorClient;

    @Override
    @Transactional
    public Integer triggerWorkflowDefinition(final WorkflowTriggerRequest triggerRequest) {
        projectService.checkHasProjectWritePermissionThrowException(
                triggerRequest.getLoginUser(), triggerRequest.getProjectCode());
        final TriggerWorkflowDTO triggerWorkflowDTO = triggerWorkflowRequestTransformer.transform(triggerRequest);
        // verify the workflow definition belongs to the URL's project
        if (triggerWorkflowDTO.getWorkflowDefinition() == null
                || triggerWorkflowDTO.getWorkflowDefinition().getProjectCode() != triggerRequest.getProjectCode()) {
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_EXIST,
                    String.valueOf(triggerRequest.getWorkflowDefinitionCode()));
        }
        // todo: use validator chain
        triggerWorkflowDTOValidator.validate(triggerWorkflowDTO);
        return executorClient.triggerWorkflowDefinition().execute(triggerWorkflowDTO);
    }

    @Override
    @Transactional
    public List<Integer> backfillWorkflowDefinition(final WorkflowBackFillRequest workflowBackFillRequest) {
        projectService.checkHasProjectWritePermissionThrowException(
                workflowBackFillRequest.getLoginUser(), workflowBackFillRequest.getProjectCode());
        final BackfillWorkflowDTO backfillWorkflowDTO =
                backfillWorkflowRequestTransformer.transform(workflowBackFillRequest);
        // verify the workflow definition belongs to the URL's project
        if (backfillWorkflowDTO.getWorkflowDefinition() == null
                || backfillWorkflowDTO.getWorkflowDefinition().getProjectCode() != workflowBackFillRequest
                        .getProjectCode()) {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the workflow definition code exists and belongs to the project in the request URL
  2. Refresh the workflow list — the definition may have been deleted
  3. Use the workflow's name lookup within the correct project to get the right code
  4. Check that projectCode in the path matches the workflow's owning project

Example fix

// before
// POST /projects/wrongProject/executors/start with code of a workflow in otherProject
// after
// POST /projects/correctProject/executors/start with the workflow code owned by that project
Defensive patterns

Strategy: validation

Validate before calling

WorkflowDefinition def = workflowDefinitionDao.queryByCode(workflowCode);
if (def == null || def.getProjectCode() != projectCode) {
    throw new IllegalStateException("Workflow " + workflowCode + " not found in project " + projectCode);
}

Try / catch

try {
    executorService.triggerWorkflowDefinition(triggerRequest);
} catch (ServiceException e) {
    if (e.getCode() == Status.WORKFLOW_DEFINITION_NOT_EXIST.getCode()) {
        // look up current code from project's workflow list and retry
    } else { throw e; }
}

Prevention

When it happens

Trigger: POST trigger with a workflowDefinitionCode that doesn't exist, or exists under another project's code while the request's projectCode doesn't match.

Common situations: Triggering via API with a code copied from a different project; workflow deleted before a scheduled trigger fires; wrong projectCode in the URL path; code type confusion (string vs long) mangling the code.

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