apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINITION_NOT_RELEASE

WORKFLOW_DEFINITION_NOT_RELEASE

Error message

WORKFLOW_DEFINITION_NOT_RELEASE

What it means

WORKFLOW_DEFINITION_NOT_RELEASE is thrown when the target workflow definition exists in the project but its releaseState is not ONLINE. The scheduler only executes workflows that are online/released, so starting an offline (draft or deprecated) workflow is rejected.

Source

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

        return executorClient.backfillWorkflowDefinition().execute(backfillWorkflowDTO);
    }

    /**
     * check whether the workflow definition can be executed
     *
     * @param projectCode       project code
     * @param workflowDefinition workflow definition
     */
    @Override
    public void checkWorkflowDefinitionValid(long projectCode, WorkflowDefinition workflowDefinition,
                                             long workflowDefinitionCode, Integer version) {
        // check workflow definition exists
        if (projectCode != workflowDefinition.getProjectCode()) {
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_EXIST, workflowDefinition.getCode());
        }
        // check workflow definition online
        if (workflowDefinition.getReleaseState() != ReleaseState.ONLINE) {
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_RELEASE, workflowDefinition.getCode(),
                    workflowDefinition.getVersion());
        }
        // check sub workflow definition online
        if (!checkSubWorkflowDefinitionValid(workflowDefinition)) {
            throw new ServiceException(Status.SUB_WORKFLOW_DEFINITION_NOT_RELEASE);
        }
    }

    /**
     * check whether the current workflow has sub workflows and validate all sub workflows
     *
     * @param workflowDefinition
     * @return check result
     */
    @Override
    public boolean checkSubWorkflowDefinitionValid(WorkflowDefinition workflowDefinition) {
        // query all sub workflows under the current workflow
        List<WorkflowTaskRelation> workflowTaskRelations =

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Release the workflow: set its release state to ONLINE via the UI or the workflow-definition release API.
  2. Then retry the execution request.
  3. If the workflow is intentionally offline, point the pipeline at a released workflow.
  4. Check for concurrent editors who took the workflow offline.

Example fix

// before
startWorkflow(code); // fails: workflow offline
// after
workflowDefinitionService.releaseWorkflowDefinition(loginUser, projectCode, code, ReleaseState.ONLINE);
startWorkflow(code);
Defensive patterns

Strategy: validation

Validate before calling

if (wf.getReleaseState() != ReleaseState.ONLINE) { /* block start, prompt to release */ }

Type guard

boolean isOnline(WorkflowDefinition wf) { return wf != null && wf.getReleaseState() == ReleaseState.ONLINE; }

Try / catch

try { executeTask(...); } catch (ServiceException e) { if (e.getCode() == Status.WORKFLOW_DEFINITION_NOT_RELEASE) { releaseDefinition(projectCode, code); retry(); } else throw e; }

Prevention

When it happens

Trigger: Calling executeTask for a workflow whose releaseState is OFFLINE; attempting to run a newly created but never released workflow; running a workflow that was taken offline (e.g. by delete-export flow or explicit offline operation).

Common situations: Creating a workflow in the UI and trying to start it without clicking 'release/online'; a CI pipeline referencing a workflow someone recently took offline for editing; after import, workflows import in offline state.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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