apache/dolphinscheduler · error · ServiceException

WORKFLOW_DEFINE_STATE_ONLINE

WORKFLOW_DEFINE_STATE_ONLINE

Error message

WORKFLOW_DEFINE_STATE_ONLINE: workflow definition [{name}] state is online, can not delete

What it means

workflowDefinitionUsedInOtherTaskValid throws this when the target workflow definition's release state is ONLINE. Deleting (or otherwise mutating) a released workflow is forbidden; it must first be taken OFFLINE via the release endpoint. This is an invalid-state-transition guard, not a data error.

Source

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

                this.deleteWorkflowDefinitionByCode(loginUser, workflowDefinition.getCode());
            } catch (Exception e) {
                throw new ServiceException(Status.DELETE_WORKFLOW_DEFINE_ERROR, workflowDefinition.getName(),
                        e.getMessage());
            }
        }
    }

    /**
     * workflow definition want to delete whether used in other task, should throw exception when have be used.
     * <p>
     * This function avoid delete workflow definition already dependencies by other tasks by accident.
     *
     * @param workflowDefinition WorkflowDefinition you change task definition and task relation
     */
    private void workflowDefinitionUsedInOtherTaskValid(User loginUser, WorkflowDefinition workflowDefinition) {
        // check workflow definition is already online
        if (workflowDefinition.getReleaseState() == ReleaseState.ONLINE) {
            throw new ServiceException(Status.WORKFLOW_DEFINE_STATE_ONLINE, workflowDefinition.getName());
        }

        // check workflow instances is already running
        List<WorkflowInstanceSummaryDto> workflowInstances =
                workflowInstanceService.queryByWorkflowDefinitionCodeAndStatus(
                        workflowDefinition.getCode(), WorkflowExecutionStatus.NOT_TERMINAL_STATES);
        if (CollectionUtils.isNotEmpty(workflowInstances)) {
            throw new ServiceException(Status.DELETE_WORKFLOW_DEFINITION_EXECUTING_FAIL, workflowInstances.size());
        }

        // check workflow used by other task, including sub workflow and dependent task type
        Optional<String> taskDepMsg = workflowLineageService.taskDependentMsg(loginUser,
                workflowDefinition.getProjectCode(), workflowDefinition.getCode(), 0);

        if (taskDepMsg.isPresent()) {
            String errorMeg = "workflow definition cannot be deleted because it has dependent, " + taskDepMsg.get();
            log.error(errorMeg);
            throw new ServiceException(errorMeg);

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Release the workflow to OFFLINE (workflowDefinitionService.releaseWorkflowDefinition) before deleting.
  2. Confirm no scheduler is depending on it, then retry the delete.
  3. If the state is stale/incorrect, fix the release state in the DB and re-attempt.

Example fix

// before
workflowDefinitionService.deleteWorkflowDefinitionByCode(loginUser, code); // ONLINE -> throws
// after
workflowDefinitionService.releaseWorkflowDefinition(loginUser, projectCode, code, ReleaseState.OFFLINE);
workflowDefinitionService.deleteWorkflowDefinitionByCode(loginUser, code);
Defensive patterns

Strategy: validation

Validate before calling

WorkflowDefinition wf = workflowDefinitionDao.queryByCode(code)
    .orElseThrow(NoSuchElementException::new);
if (wf.getReleaseState() == ReleaseState.ONLINE) {
    workflowDefinitionService.releaseWorkflowDefinition(user, projectCode, code, ReleaseState.OFFLINE);
}

Try / catch

try { service.deleteWorkflowDefinitionByCode(user, code); }
catch (ServiceException e) { if (e.getCode() == Status.WORKFLOW_DEFINE_STATE_ONLINE) { /* offline first, retry */ } }

Prevention

When it happens

Trigger: Calling deleteWorkflowDefinitionByCode / batch delete on a workflow that was published (releaseState=ONLINE) and never switched back to OFFLINE.

Common situations: CI scripts that delete workflows without releasing them first; users clicking delete on a running production workflow; migration scripts importing new versions while the old released one remains.

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