apache/dolphinscheduler · error · IllegalArgumentException

The workflowDefinition should not be null

Error message

The workflowDefinition should not be null

What it means

TriggerWorkflowDTOValidator.validate requires the workflowDefinition on the trigger DTO to be non-null. A null definition means the request does not reference a concrete workflow to run, so the validator throws IllegalArgumentException('The workflowDefinition should not be null').

Source

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

public class TriggerWorkflowDTOValidator implements IValidator<TriggerWorkflowDTO> {

    private final TenantExistValidator tenantExistValidator;

    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. Verify the workflow code/name exists and pass a correctly fetched WorkflowDefinition into the DTO.
2. Check the controller/service code that populates workflowDefinition for ignored failed lookups.
3. Re-fetch the workflow list to confirm it was not deleted concurrently.
4. Set workflowDefinition explicitly when constructing TriggerWorkflowDTO programmatically.

Example fix

// before
TriggerWorkflowDTO dto = new TriggerWorkflowDTO();
dto.setExecType(CommandType.START_PROCESS); // definition never set
// after
dto.setWorkflowDefinition(workflowDefinitionService.findWorkflowDefinitionByCode(code));

if (!dto.workflowDefinition) {
  throw new Error('workflowDefinition must be loaded before triggering');
}

function hasDefinition(dto) {
  return dto?.workflowDefinition != null && typeof dto.workflowDefinition === 'object';
}

try {
  trigger(dto);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("workflowDefinition should not be null")) {
    // re-fetch definition by code and retry
  }
}

When it happens

Trigger: Triggering a workflow where the DTO's workflowDefinition was never populated — e.g. the workflow code/name in the request matched nothing and the assembly step left the field null, or the DTO was hand-built without the definition.

Common situations: Triggering a deleted or nonexistent workflow; typo in workflow name/code so lookup fails silently; scripts calling internal APIs without fetching the definition; race condition where the workflow was deleted between selection and trigger.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• 10105
• The workflowDefinition should not be null
• The releaseState {releaseState} is illegal, please check it.
• no master server available
• Trigger workflow failed: %s

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