apache/dolphinscheduler · error · ServiceException

50003

50003

Error message

workflow definition {0} does not exist

What it means

Thrown by queryWorkflowDefinitionByCode when no workflow definition exists with the given code, or when the found definition belongs to a different project than the projectCode path parameter. The API treats both cases as not-found to avoid leaking cross-project data.

Source

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

    /**
     * query detail of workflow definition
     *
     * @param loginUser   login user
     * @param projectCode project code
     * @param code        workflow definition code
     * @return workflow definition detail
     */
    @Override
    public DagData queryWorkflowDefinitionByCode(User loginUser, long projectCode, long code) {
        Project project = projectDao.queryByCode(projectCode);
        // check user access for project
        projectService.checkProjectAndAuthThrowException(loginUser, project, WORKFLOW_DEFINITION);

        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));
        }
        return processService.genDagData(workflowDefinition);
    }

    @Override
    public Optional<WorkflowDefinition> queryWorkflowDefinition(long workflowDefinitionCode,
                                                                int workflowDefinitionVersion) {
        WorkflowDefinition workflowDefinition = workflowDefinitionDao.queryByCode(workflowDefinitionCode).orElse(null);
        if (workflowDefinition == null || workflowDefinition.getVersion() != workflowDefinitionVersion) {
            workflowDefinition = workflowDefinitionLogDao.queryByDefinitionCodeAndVersion(workflowDefinitionCode,
                    workflowDefinitionVersion);
        }
        return Optional.ofNullable(workflowDefinition);
    }

    @Override
    public WorkflowDefinition queryWorkflowDefinitionThrowExceptionIfNotFound(long workflowDefinitionCode,
                                                                              int workflowDefinitionVersion) {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the workflow code via the workflow-definition list API for the given projectCode
  2. Ensure the projectCode path segment matches the project that actually owns the workflow
  3. Re-create the workflow if it was deleted (codes are not reusable)

Example fix

// before
GET /projects/123/workflow-definition/99999999
// after
list = GET /projects/123/workflow-definition/list  → find correct code → GET /projects/123/workflow-definition/{code}
Defensive patterns

Strategy: try-catch

Validate before calling

Optional<WorkflowDefinition> def = workflowDefinitionDao.queryByCode(code);
boolean usable = def.isPresent() && def.get().getProjectCode() == projectCode;

Type guard

static boolean workflowExistsInProject(WorkflowDefinition d, long projectCode) { return d != null && d.getProjectCode() == projectCode; }

Try / catch

try { return api.queryWorkflowDefinitionByCode(projectCode, code); } catch (ServiceException e) { if (e.getCode() == 50003) { /* re-list definitions to refresh codes */ } }

Prevention

When it happens

Trigger: GET /projects/{projectCode}/workflow-definition/{code} with a wrong or deleted code, or a valid code that belongs to another projectCode.

Common situations: Stale cached workflow code after the workflow was deleted; copying a code between environments where codes differ; using the wrong projectCode in the URL path.

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