apache/dolphinscheduler · error · IllegalArgumentException

The execType should be START_PROCESS

Error message

The execType should be START_PROCESS

What it means

BackfillWorkflowDTOValidator.validate requires the workflow's execType to be CommandType.COMPLEMENT_DATA for a backfill. The message text says START_PROCESS but the actual comparison in this validator is execType != COMPLEMENT_DATA, so any other exec type triggers IllegalArgumentException('The execType should be START_PROCESS'). Backfill is implemented as a complement-data execution, so other start types are rejected.

Source

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

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

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

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set execType to CommandType.COMPLEMENT_DATA in the backfill request.
2. Verify you are calling the backfill endpoint, not the trigger endpoint; trigger requires START_PROCESS instead.
3. Update client/SDK defaults so backfill requests use COMPLEMENT_DATA.
4. If you intend a normal run, use the trigger API with execType START_PROCESS instead of the backfill API.

Example fix

// before
dto.setExecType(CommandType.START_PROCESS); // used backfill endpoint
// after
dto.setExecType(CommandType.COMPLEMENT_DATA); // required by BackfillWorkflowDTOValidator

if (dto.execType !== 'COMPLEMENT_DATA') {
  throw new Error('Backfill requires execType COMPLEMENT_DATA');
}

function isBackfillExecType(dto) {
  return dto?.execType === 'COMPLEMENT_DATA';
}

try {
  backfill(dto);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("execType should be")) {
    // switch endpoint or fix execType and retry
  }
}

When it happens

Trigger: Submitting a backfill request whose execType is START_PROCESS, RECOVER_TOLERANCE_FAULT_PROCESS, SCHEDULER, or any CommandType other than COMPLEMENT_DATA.

Common situations: Reusing a 'run workflow' client payload for the backfill endpoint; confusing the backfill endpoint with the trigger endpoint (which does require START_PROCESS); SDK defaulting execType to START_PROCESS; server-side copy of an older trigger validator wording.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• backfillParams is null
• backfillDateList is empty
• expectedParallelismNumber should >= 0
• The execType should be START_PROCESS
• url can not be null

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