apache/dolphinscheduler · error · ServiceException

Trigger workflow failed: %s

Error message

Trigger workflow failed: %s

What it means

Thrown by TriggerWorkflowExecutorDelegate.execute when the master's manualTriggerWorkflow response reports success=false. The trigger request reached a master but the master refused to start the workflow run; the master's message is appended to explain why.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/TriggerWorkflowExecutorDelegate.java:53

@Slf4j
@Component
public class TriggerWorkflowExecutorDelegate implements IExecutorDelegate<TriggerWorkflowDTO, Integer> {

    @Autowired
    private RegistryClient registryClient;

    @Override
    public Integer execute(final TriggerWorkflowDTO triggerWorkflowDTO) {
        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);
        if (masterServer == null) {
            throw new ServiceException("no master server available");
        }
        final WorkflowManualTriggerResponse workflowManualTriggerResponse = Clients
                .withService(IWorkflowControlClient.class)
                .withHost(masterServer.getHost() + ":" + masterServer.getPort())
                .manualTriggerWorkflow(transform2WorkflowTriggerRequest(triggerWorkflowDTO));
        if (!workflowManualTriggerResponse.isSuccess()) {
            throw new ServiceException("Trigger workflow failed: " + workflowManualTriggerResponse.getMessage());
        }
        return workflowManualTriggerResponse.getWorkflowInstanceId();

    }

    private WorkflowManualTriggerRequest transform2WorkflowTriggerRequest(TriggerWorkflowDTO triggerWorkflowDTO) {
        return WorkflowManualTriggerRequest.builder()
                .userId(triggerWorkflowDTO.getLoginUser().getId())
                .workflowDefinitionCode(triggerWorkflowDTO.getWorkflowDefinition().getCode())
                .workflowDefinitionVersion(triggerWorkflowDTO.getWorkflowDefinition().getVersion())
                .startNodes(triggerWorkflowDTO.getStartNodes())
                .failureStrategy(triggerWorkflowDTO.getFailureStrategy())
                .taskDependType(triggerWorkflowDTO.getTaskDependType())
                .warningType(triggerWorkflowDTO.getWarningType())
                .warningGroupId(triggerWorkflowDTO.getWarningGroupId())
                .workflowInstancePriority(triggerWorkflowDTO.getWorkflowInstancePriority())
                .workerGroup(triggerWorkflowDTO.getWorkerGroup())
                .tenantCode(triggerWorkflowDTO.getTenantCode())

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Read the appended workflowManualTriggerResponse.getMessage() for the master's reason
  2. Ensure the workflow definition exists and is in ONLINE release state
  3. Validate trigger params (start nodes, command params JSON) before calling the API
  4. Confirm the user/tenant has permission on the workflow's project
  5. Check master logs at trigger time for the detailed failure

Example fix

// before
manualTriggerWorkflow(transform2WorkflowTriggerRequest(triggerWorkflowDTO));
// after
// pre-validate definition state
WorkflowDefinition def = workflowDefinitionDao.findByName(projectCode, triggerWorkflowDTO.getName());
if (def == null || def.getReleaseState() != ReleaseState.ONLINE) {
    throw new ServiceException("Workflow must be online to trigger");
}
Defensive patterns

Strategy: validation

Validate before calling

WorkflowDefinition def = workflowDefinitionDao.findByName(projectCode, dto.getName());
if (def == null || def.getReleaseState() != ReleaseState.ONLINE) {
    throw new IllegalStateException("Workflow must exist and be online to trigger");
}

Try / catch

try {
    Integer instanceId = delegate.execute(dto);
} catch (ServiceException e) {
    log.error("Trigger failed: {}", e.getMessage(), e);
    // show master-side message to the user
}

Prevention

When it happens

Trigger: manualTriggerWorkflow returning success=false — e.g. the workflow definition is offline/undeleted, the project/definition doesn't exist on the master, invalid trigger params (command params, start nodes, schedules), or command generation failure on the master.

Common situations: Triggering a workflow whose definition was taken offline; passing bad start-node names or parameter JSON; tenant/user lacking rights on the target project; master-side DB errors when creating the command.

Related errors

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