apache/dolphinscheduler · error · ServiceException

ALERT_GROUP_EXIST

ALERT_GROUP_EXIST

Error message

ALERT_GROUP_EXIST

What it means

DolphinScheduler throws this when creating an alert group fails because the group name already exists. The insert/update hits a unique key on the alert group name, Spring translates the database DuplicateKeyException into ServiceException(Status.ALERT_GROUP_EXIST). It prevents duplicate-named alert groups.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/AlertGroupServiceImpl.java:173

        alertGroup.setGroupName(groupName);
        alertGroup.setAlertInstanceIds(alertInstanceIds);
        alertGroup.setDescription(desc);
        alertGroup.setCreateTime(now);
        alertGroup.setUpdateTime(now);
        alertGroup.setCreateUserId(loginUser.getId());

        // insert
        try {
            int insert = alertGroupDao.insert(alertGroup);
            if (insert > 0) {
                log.info("Create alert group complete, groupName:{}", alertGroup.getGroupName());
                return alertGroup;
            }
            log.error("Create alert group error, groupName:{}", alertGroup.getGroupName());
            throw new ServiceException(Status.CREATE_ALERT_GROUP_ERROR);
        } catch (DuplicateKeyException ex) {
            log.error("Create alert group error, groupName:{}", alertGroup.getGroupName(), ex);
            throw new ServiceException(Status.ALERT_GROUP_EXIST);
        }
    }

    /**
     * updateWorkflowInstance alert group
     *
     * @param loginUser login user
     * @param id alert group id
     * @param groupName group name
     * @param desc description
     * @param alertInstanceIds alertInstanceIds
     * @return update result code
     */
    @Override
    public AlertGroup updateAlertGroupById(User loginUser, int id, String groupName, String desc,
                                           String alertInstanceIds) {
        if (!canOperatorPermissions(loginUser, new Object[]{id}, AuthorizationType.ALERT_GROUP, ALERT_GROUP_UPDATE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Pick a different, unique groupName for the new alert group
  2. Query existing groups first (list-alert-groups) and skip creation if the name already exists
  3. In automation, catch the exception and treat ALERT_GROUP_EXIST as idempotent success
  4. Verify the DB unique index on group_name is intended before bulk-importing groups

Example fix

// before
alertGroupService.createAlertGroup(loginUser, "ops-team", "oncall", "");
// after
if (alertGroupService.queryAlertGroupByGroupName("ops-team") == null) {
    alertGroupService.createAlertGroup(loginUser, "ops-team", "oncall", "");
}
Defensive patterns

Strategy: try-catch

Validate before calling

List<AlertGroup> groups = alertGroupService.queryAllAlertGroup(loginUser);
boolean exists = groups.stream().anyMatch(g -> g.getGroupName().equals(name));
if (exists) throw new IllegalArgumentException("group name already in use: " + name);

Try / catch

try {
    alertGroupService.createAlertGroup(loginUser, name, desc, "");
} catch (ServiceException e) {
    if (e.getCode() == Status.ALERT_GROUP_EXIST) { /* handle duplicate */ }
    else throw e;
}

Prevention

When it happens

Trigger: Calling POST /alert-groups (AlertGroupService.createAlertGroup) with a groupName that already exists in t_ds_alert_group, causing a unique-key violation on insert.

Common situations: Re-running a setup script or automation that creates alert groups without checking existence; two admins creating the same group name concurrently; restoring/migrating groups that already exist in the target environment.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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