apache/dolphinscheduler · error · IllegalArgumentException

The workflowDefinition should not be null

Error message

The workflowDefinition should not be null

What it means

BackfillWorkflowDTOValidator.validate requires workflowDefinition on the DTO to be non-null, since backfill operates on a concrete workflow definition. If backfillWorkflowDTO.getWorkflowDefinition() is null, it throws IllegalArgumentException('The workflowDefinition should not be null').

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/validator/workflow/BackfillWorkflowDTOValidator.java:62

    }

    @Override
    public void validate(final BackfillWorkflowDTO backfillWorkflowDTO) {
        final BackfillWorkflowDTO.BackfillParamsDTO backfillParams = backfillWorkflowDTO.getBackfillParams();
        if (backfillParams == null) {
            throw new IllegalArgumentException("backfillParams is null");
        }
        if (CollectionUtils.isEmpty(backfillParams.getBackfillDateList())) {
            throw new IllegalArgumentException("backfillDateList is empty");
        }
        if (backfillParams.getExpectedParallelismNumber() < 0) {
            throw new IllegalArgumentException("expectedParallelismNumber should >= 0");
        }
        if (backfillWorkflowDTO.getExecType() != CommandType.COMPLEMENT_DATA) {
            throw new IllegalArgumentException("The execType should be START_PROCESS");
        }
        if (backfillWorkflowDTO.getWorkflowDefinition() == null) {
            throw new IllegalArgumentException("The workflowDefinition should not be null");
        }
        if (backfillWorkflowDTO.getWorkflowDefinition().getReleaseState() != ReleaseState.ONLINE) {
            throw new IllegalStateException("The workflowDefinition should be online");
        }

        tenantExistValidator.validate(backfillWorkflowDTO.getTenantCode());

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

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Confirm the target workflow exists (correct code/name) and was fetched before building the request.
2. Set workflowDefinition explicitly when constructing BackfillWorkflowDTO programmatically.
3. Check upstream code that populates the DTO (controller/service layer) for failed lookups being ignored.
4. Re-fetch the workflow list to ensure it was not deleted concurrently.

Example fix

// before
BackfillWorkflowDTO dto = new BackfillWorkflowDTO();
// workflowDefinition never attached
// after
dto.setWorkflowDefinition(workflowDefinitionService.findWorkflowDefinitionByCode(code));

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

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

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

When it happens

Trigger: A backfill request where the server-side lookup/assembly step failed to attach the WorkflowDefinition (e.g. unknown workflow name/code) or the caller built the DTO manually without the definition.

Common situations: Referencing a workflow that does not exist or was deleted so the enrichment step leaves the field null; calling an internal API directly in scripts/tests without loading the definition first; race where the workflow is dropped between listing and backfilling.

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
• backfillParams is null
• The workflowDefinition should not be null
• The releaseState {releaseState} is illegal, please check it.
• Backfill workflow failed: %s

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