apache/dolphinscheduler · error · IllegalArgumentException

backfillParams is null

Error message

backfillParams is null

What it means

BackfillWorkflowDTOValidator.validate performs mandatory-field checks on a workflow backfill request. The backfillParams field of BackfillWorkflowDTO must be present; if it is null, the validator throws IllegalArgumentException('backfillParams is null') before any further validation. Backfilling (complementing historical dates) is impossible without the parameters that carry dates, parallelism and start params.

Source

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

@Slf4j
@Component
public class BackfillWorkflowDTOValidator implements IValidator<BackfillWorkflowDTO> {

    private final TenantExistValidator tenantExistValidator;

    private final StartParamListValidator startParamListValidator;

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

    @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());

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Include a non-null backfillParams object (with backfillDateList, expectedParallelismNumber, startParamList) in the backfill request body.
2. Fix JSON field names to match BackfillWorkflowDTO.BackfillParamsDTO property names so deserialization populates the field.
3. Check the client/SDK version matches the server API schema; upgrade the client if backfillParams was recently added.
4. Validate/construct the DTO via its builder so backfillParams is always set.

Example fix

// before
BackfillWorkflowDTO dto = new BackfillWorkflowDTO();
dto.setExecType(CommandType.COMPLEMENT_DATA); // backfillParams never set
// after
BackfillWorkflowDTO dto = new BackfillWorkflowDTO();
dto.setBackfillParams(BackfillWorkflowDTO.BackfillParamsDTO.builder()
    .backfillDateList(dates).expectedParallelismNumber(1).build());

if (!dto.backfillParams) {
  throw new Error('backfillParams must be provided');
}

function hasBackfillParams(dto) {
  return dto != null && dto.backfillParams != null && typeof dto.backfillParams === 'object';
}

try {
  backfill(dto);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("backfillParams is null")) {
    // rebuild DTO with backfillParams before retrying
  }
}

When it happens

Trigger: Submitting a backfill workflow API request whose JSON body omits the backfillParams object entirely, or programmatically constructing a BackfillWorkflowDTO without calling setBackfillParams before passing it to validate().

Common situations: Client SDK sending an empty/partial body; a JSON field-name typo (backfill_params vs backfillParams) silently deserializing to null; upgrading API clients after the backfill schema changed; hand-built DTOs in tests or scripts.

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

• backfillDateList is empty
• expectedParallelismNumber should >= 0
• The execType should be START_PROCESS
• The workflowDefinition should not be null
• projectUser must not be null

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