apache/dolphinscheduler · error · IllegalStateException

The workflowDefinition should be online

Error message

The workflowDefinition should be online

What it means

TriggerWorkflowDTOValidator.validate() refuses to build a trigger for a workflow definition whose release state is not ONLINE. DolphinScheduler only allows starting/triggerring runs of workflow definitions that have been published (released); a draft or offline workflow cannot be executed. This is an IllegalStateException because the request itself is well-formed but the workflow is in a state that forbids execution.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/validator/workflow/TriggerWorkflowDTOValidator.java:53

    private final StartParamListValidator startParamListValidator;

    public TriggerWorkflowDTOValidator(TenantExistValidator tenantExistValidator,
                                       StartParamListValidator startParamListValidator) {
        this.tenantExistValidator = tenantExistValidator;
        this.startParamListValidator = startParamListValidator;
    }

    @Override
    public void validate(final TriggerWorkflowDTO triggerWorkflowDTO) {
        if (triggerWorkflowDTO.getExecType() != CommandType.START_PROCESS) {
            throw new IllegalArgumentException("The execType should be START_PROCESS");
        }
        if (triggerWorkflowDTO.getWorkflowDefinition() == null) {
            throw new IllegalArgumentException("The workflowDefinition should not be null");
        }
        if (triggerWorkflowDTO.getWorkflowDefinition().getReleaseState() != ReleaseState.ONLINE) {
            throw new IllegalStateException("The workflowDefinition should be online");
        }

        tenantExistValidator.validate(triggerWorkflowDTO.getTenantCode());

        startParamListValidator.validate(triggerWorkflowDTO.getStartParamList());
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Open the workflow in the DolphinScheduler UI and click 'Release' (set ReleaseState to ONLINE), or call the release API to publish the definition before triggering.
2. Verify via the API (GET workflow definition) that releaseState == ONLINE for the code you are triggering; if a different version is offline, release the correct one.
3. If the workflow was intentionally taken offline, stop/disable the schedules or automation that trigger it, or re-create/re-release a new version.

Example fix

// before (definition is draft/offline)
triggerWorkflowDefinition(definitionCode);

// after: release the definition first
WorkflowDefinition def = queryDefinition(definitionCode);
if (def.getReleaseState() != ReleaseState.ONLINE) {
    workflowDefinitionService.releaseDefinition(loginUser, definitionCode, ReleaseState.ONLINE);
}
triggerWorkflowDefinition(definitionCode);

WorkflowDefinition def = triggerWorkflowDTO.getWorkflowDefinition();
if (def == null || def.getReleaseState() != ReleaseState.ONLINE) {
    throw new IllegalStateException("Workflow " + def.getCode() + " is not ONLINE; release it before triggering");
}

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

When it happens

Trigger: Calling the workflow trigger/start API (or the scheduler-internal path that validates TriggerWorkflowDTO) while the target workflow definition's releaseState is OFFLINE or DRAFT, typically via POST /dolphinscheduler/workflows/{code}/trigger or startProcessInstance with an offline definition.

Common situations: Users attempt to run a workflow they created but never clicked 'Release'/'Online'; a workflow was taken offline for editing while scheduled or manual triggers still reference it; automation scripts hit an old definition that was later taken offline.

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

• 50004
• WORKFLOW_DEFINITION_NOT_RELEASE
• SUB_WORKFLOW_DEFINITION_NOT_RELEASE
• SCHEDULE_ALREADY_EXISTS
• SCHEDULE_START_TIME_END_TIME_SAME

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