apache/dolphinscheduler · error · ServiceException

SubWorkflowDefinition {subWorkflowDefinition name} is not on

Error message

SubWorkflowDefinition {subWorkflowDefinition name} is not online

What it means

Thrown when validating a workflow whose sub-workflow tasks reference a sub-workflow definition that is not in ONLINE release state. A parent workflow cannot be released/deployed while any of its dependent sub-workflows remains offline, because the scheduler could not execute them. Note the message string embeds the sub-workflow name.

Source

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

        }
        List<TaskDefinitionLog> taskDefinitionLogs =
                taskDefinitionLogDao.queryTaskDefineLogList(workflowTaskRelations);
        taskDatasourcePermissionChecker.checkPermission(loginUser, taskDefinitionLogs);
        taskSubWorkflowPermissionChecker.checkPermission(loginUser, taskDefinitionLogs);
        // todo : check Workflow is validate
    }

    private void checkAllSubWorkflowDefinitionIsOnline(Long workflowDefinitionCode) {
        List<Long> allSubWorkflowDefinitionCodes =
                processService.findAllSubWorkflowDefinitionCode(workflowDefinitionCode);
        if (CollectionUtils.isEmpty(allSubWorkflowDefinitionCodes)) {
            return;
        }
        for (Long subWorkflowDefinitionCode : allSubWorkflowDefinitionCodes) {
            WorkflowDefinition subWorkflowDefinition = workflowDefinitionDao.queryByCode(subWorkflowDefinitionCode)
                    .orElseThrow(() -> new ServiceException(WORKFLOW_DEFINITION_NOT_EXIST, workflowDefinitionCode));
            if (!ReleaseState.ONLINE.equals(subWorkflowDefinition.getReleaseState())) {
                throw new ServiceException(
                        "SubWorkflowDefinition " + subWorkflowDefinition.getName() + " is not online");
            }
        }
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

Bring every referenced sub-workflow definition ONLINE before releasing the parent workflow.
Check each SUB_PROCESS task's target code's release state via the workflow definition API.
If a sub-workflow is intentionally retired, remove or repoint the parent's SUB_PROCESS task first.
After imports, batch-release sub-workflows (deepest dependencies first) before parents.

Example fix

// before: releasing parent while sub-workflow offline
workflowDefinitionService.releaseWorkflowDefinition(user, projectCode, parentCode, ReleaseState.ONLINE);
// after: ensure subs online
for (long subCode : allSubWorkflowDefinitionCodes) {
    workflowDefinitionService.releaseWorkflowDefinition(user, subProjectCode, subCode, ReleaseState.ONLINE);
}
workflowDefinitionService.releaseWorkflowDefinition(user, projectCode, parentCode, ReleaseState.ONLINE);

Defensive patterns

Strategy: validation

Validate before calling

for (Long subCode : allSubWorkflowDefinitionCodes) {
    WorkflowDefinition sub = workflowDefinitionDao.queryByCode(subCode).orElseThrow();
    if (!ReleaseState.ONLINE.equals(sub.getReleaseState())) {
        throw new IllegalStateException("sub-workflow " + sub.getName() + " must be ONLINE before releasing parent");
    }
}

Type guard

boolean allSubWorkflowsOnline(Collection<WorkflowDefinition> subs) {
    return subs.stream().allMatch(s -> ReleaseState.ONLINE.equals(s.getReleaseState()));
}

Try / catch

try {
    service.releaseWorkflowDefinition(user, projectCode, parentCode, ReleaseState.ONLINE);
} catch (ServiceException e) {
    if (e.getMessage() != null && e.getMessage().contains("is not online")) {
        // online the named sub-workflow, then retry
    } else throw e;
}

Prevention

Release sub-workflows before parents, in dependency order.
Do not take sub-workflows offline while a parent references them.
After imports, batch-verify release states of the whole workflow graph.

When it happens

Trigger: Releasing (online) a parent workflow containing SUB_PROCESS tasks whose target workflow definitions have ReleaseState != ONLINE; also occurs when a sub-workflow was taken offline after the parent referenced it.

Common situations: Taking sub-workflows offline for maintenance while the parent stays online; fresh environment imports where parents are online but sub-workflows import as offline; renaming/recreating a sub-workflow so the parent points at a new offline definition.

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