apache/dolphinscheduler · error · IllegalArgumentException

expectedParallelismNumber should >= 0

Error message

expectedParallelismNumber should >= 0

What it means

BackfillWorkflowDTOValidator.validate checks that backfillParams.expectedParallelismNumber is non-negative. A negative value would mean an invalid number of parallel complement instances, so the validator throws IllegalArgumentException('expectedParallelismNumber should >= 0').

Source

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

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

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

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set expectedParallelismNumber to a value >= 0 (0 usually means serial/no parallelism).
2. Fix the client to omit/nullify the field instead of sending -1 when the user did not choose a value.
3. Clamp user input in the UI: max(0, parsedValue) before building the request.
4. Add client-side validation with a clear message before the API call.

Example fix

// before
params.setExpectedParallelismNumber(-1); // sentinel for 'unset'
// after
params.setExpectedParallelismNumber(Math.max(0, requestedParallelism));

if (params.expectedParallelismNumber == null || params.expectedParallelismNumber < 0) {
  throw new Error('expectedParallelismNumber must be >= 0');
}

function hasValidParallelism(params) {
  return Number.isInteger(params?.expectedParallelismNumber) && params.expectedParallelismNumber >= 0;
}

try {
  backfill(dto);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("expectedParallelismNumber")) {
    // clamp to >= 0 and retry once
  }
}

When it happens

Trigger: A backfill request whose backfillParams.expectedParallelismNumber is negative (e.g. -1), typically from a client defaulting to -1 to mean 'unset' and sending it as-is.

Common situations: Front-end leaving the parallelism input blank and sending -1 as a sentinel; script/SDK constructing params with an uninitialized int; copying a request example and editing parallelism down to test limits.

Related errors

• backfillParams is null
• backfillDateList is empty
• The execType should be START_PROCESS
• url can not be null
• 10001

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