apache/dolphinscheduler · error · IllegalStateException

The workflowDefinition should be online

Error message

The workflowDefinition should be online

What it means

BackfillWorkflowDTOValidator.validate requires the target workflow definition to be released/online before it can be backfilled. If workflowDefinition.getReleaseState() != ReleaseState.ONLINE, it throws IllegalStateException('The workflowDefinition should be online'). Backfilling an offline (draft or unpublished) workflow is disallowed.

Source

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

    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. Publish the workflow first: set its release state to ONLINE via the release API/UI, then retry the backfill.
  2. Verify you selected the intended (published) workflow, not a draft copy.
  3. Refresh the workflow's current release state before backfilling to avoid a stale OFFLINE snapshot.
  4. Add a pre-check in automation: skip/abort backfill if releaseState != ONLINE.

Example fix

// before
if (definition.getReleaseState() != ReleaseState.ONLINE) { backfill(dto); } // throws
// after
releaseService.onlineWorkflow(definition.getCode(), user);
// then retry backfill once releaseState == ReleaseState.ONLINE
Defensive patterns

Strategy: validation

Validate before calling

if (definition.releaseState !== 'ONLINE') {
  throw new Error('Workflow must be ONLINE (published) before backfill');
}

Type guard

function isOnline(definition) {
  return definition?.releaseState === 'ONLINE';
}

Try / catch

try {
  backfill(dto);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("should be online")) {
    // publish workflow via release API, then retry
  }
}

Prevention

When it happens

Trigger: Requesting a backfill for a workflow whose releaseState is OFFLINE, i.e. it was never published, or was taken offline after the DTO was built.

Common situations: Trying to backfill a newly created draft workflow; someone unpublished the workflow between listing it and submitting the backfill; copying a workflow and forgetting to publish the copy; CI scripts backfilling against a staging workflow left offline.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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