apache/dolphinscheduler · error · ServiceException

SUB_WORKFLOW_DEFINITION_NOT_RELEASE

SUB_WORKFLOW_DEFINITION_NOT_RELEASE

Error message

SUB_WORKFLOW_DEFINITION_NOT_RELEASE

What it means

SUB_WORKFLOW_DEFINITION_NOT_RELEASE is thrown when the target workflow is online but at least one nested sub-workflow referenced by a SUB_PROCESS task is offline. checkSubWorkflowDefinitionValid recursively validates child workflows, and the executor refuses to start a parent whose dependency chain contains an offline sub-workflow.

Source

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

     *
     * @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 =
                workflowTaskRelationDao.queryDownstreamByWorkflowDefinitionCode(workflowDefinition.getCode());
        if (workflowTaskRelations.isEmpty()) {
            return true;
        }
        Set<Long> relationCodes =

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Identify the offline sub-workflow (check all SUB_PROCESS task targets) and release it to ONLINE.
  2. Release every nested sub-workflow in the chain, then retry.
  3. Temporarily inline the sub-workflow logic if the sub-workflow must stay offline.

Example fix

// before: only parent released
release(parentCode);
execute(parentCode); // fails
// after
release(parentCode);
release(subWorkflowCodeFromSubProcessTask);
execute(parentCode);
Defensive patterns

Strategy: validation

Validate before calling

boolean allSubWorkflowsOnline = workflowDefinitionService.querySubWorkflowDefinitions(projectCode, wf.getCode())
    .stream().allMatch(d -> d.getReleaseState() == ReleaseState.ONLINE);

Try / catch

try { executeTask(...); } catch (ServiceException e) { if (e.getCode() == Status.SUB_WORKFLOW_DEFINITION_NOT_RELEASE) { /* find and release offline sub-workflow, then retry */ } else throw e; }

Prevention

When it happens

Trigger: Executing a workflow containing a SUB_PROCESS task whose sub-workflow definition has releaseState != ONLINE, at any depth of nesting.

Common situations: Someone released only the parent workflow but forgot the sub-workflows; a sub-workflow was taken offline for editing while the parent stayed online; newly imported workflows with nested dependencies 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/aa065dca6c32f67d. Report an issue: GitHub.