apache/dolphinscheduler · warning · IllegalArgumentException

warningGroupId of the workflow instance must not be null

Error message

warningGroupId of the workflow instance must not be null

What it means

sendWorkflowTimeoutAlert() uses workflowInstance.getWarningGroupId() as the alert group; if it is null the method cannot determine which alert group to notify and throws IllegalArgumentException. A valid warning group must be set on the workflow definition before the instance runs.

Source

Thrown at dolphinscheduler-dao/src/main/java/org/apache/dolphinscheduler/dao/AlertDao.java:209

        // we use this method to avoid insert duplicate alert(issue #5525)
        // we modified this method to optimize performance(issue #9174)
        Date crashAlarmSuppressionStartTime = Date.from(
                LocalDateTime.now().plusMinutes(-crashAlarmSuppression).atZone(ZoneId.systemDefault()).toInstant());
        alertMapper.insertAlertWhenServerCrash(alert, crashAlarmSuppressionStartTime);
    }

    /**
     * workflow time out alert
     *
     * @param workflowInstance workflowInstance
     * @param projectUser     projectUser
     */
    public void sendWorkflowTimeoutAlert(WorkflowInstance workflowInstance, ProjectUser projectUser) {
        if (projectUser == null) {
            throw new IllegalArgumentException("projectUser must not be null");
        }
        if (workflowInstance.getWarningGroupId() == null) {
            throw new IllegalArgumentException("warningGroupId of the workflow instance must not be null");
        }

        int alertGroupId = workflowInstance.getWarningGroupId();
        Alert alert = new Alert();
        List<WorkflowAlertContent> workflowAlertContentList = new ArrayList<>(1);
        WorkflowAlertContent workflowAlertContent = WorkflowAlertContent.builder()
                .projectCode(projectUser.getProjectCode())
                .projectName(projectUser.getProjectName())
                .owner(projectUser.getUserName())
                .workflowInstanceId(workflowInstance.getId())
                .workflowDefinitionCode(workflowInstance.getWorkflowDefinitionCode())
                .workflowInstanceName(workflowInstance.getName())
                .commandType(workflowInstance.getCommandType())
                .workflowExecutionStatus(workflowInstance.getState())
                .runTimes(workflowInstance.getRunTimes())
                .workflowStartTime(workflowInstance.getStartTime())
                .workflowHost(workflowInstance.getHost())
                .event(AlertEvent.TIME_OUT)

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Set a warning group (alert group) on the workflow definition in the UI/API and re-save.
2. Backfill warning_group_id for affected workflow definitions in the database.
3. In callers, check workflowInstance.getWarningGroupId() != null before invoking the alert.
4. Configure a default alert group for workflows so new definitions always have one.

Example fix

// before
alertDao.sendWorkflowTimeoutAlert(workflowInstance, projectUser);
// after
if (workflowInstance.getWarningGroupId() != null) {
    alertDao.sendWorkflowTimeoutAlert(workflowInstance, projectUser);
}

if (workflowInstance.getWarningGroupId() == null) {
    log.warn("Workflow {} has no warning group; skip timeout alert", workflowInstance.getId());
    return;
}

try {
    alertDao.sendWorkflowTimeoutAlert(workflowInstance, projectUser);
} catch (IllegalArgumentException e) {
    log.warn("Alert not sent: {}", e.getMessage());
}

When it happens

Trigger: Triggering a workflow timeout alert for an instance whose workflow definition has no warning group configured (warningGroupId is NULL in the workflow definition / instance), e.g. the definition was saved without selecting an alert group.

Common situations: Workflows created via API or import without a warningGroupId; older workflow definitions predating the warning-group requirement; UI race where timeout fires for a definition saved with empty alert group.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Recover workflow instance failed: %s
• The workflow instance: %s status is %s, cannot repeat runnin
• Repeat running workflow instance failed: %s
• The workflow instance: %s status is %s, can not stop
• WorkflowInstance: %s stop failed: %s

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