apache/dolphinscheduler · error · ServiceException

PLUGIN_INSTANCE_ALREADY_EXISTS

PLUGIN_INSTANCE_ALREADY_EXISTS

Error message

PLUGIN_INSTANCE_ALREADY_EXISTS

What it means

Thrown by AlertPluginInstanceServiceImpl.create when an alert plugin instance with the same instanceName already exists (existInstanceName returns true). Instance names must be unique among alert plugin instances.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/AlertPluginInstanceServiceImpl.java:111

     */
    @Override
    public AlertPluginInstance create(User loginUser,
                                      int pluginDefineId,
                                      String instanceName,
                                      String pluginInstanceParams) {

        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ALERT_PLUGIN_INSTANCE, ALERT_INSTANCE_CREATE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);
        }

        AlertPluginInstance alertPluginInstance = new AlertPluginInstance();
        String paramsMapJson = parsePluginParamsMap(pluginInstanceParams);
        alertPluginInstance.setPluginInstanceParams(paramsMapJson);
        alertPluginInstance.setInstanceName(instanceName);
        alertPluginInstance.setPluginDefineId(pluginDefineId);

        if (alertPluginInstanceMapper.existInstanceName(alertPluginInstance.getInstanceName()) == Boolean.TRUE) {
            throw new ServiceException(Status.PLUGIN_INSTANCE_ALREADY_EXISTS);
        }

        int i = alertPluginInstanceMapper.insert(alertPluginInstance);
        if (i > 0) {
            log.info("Create alert plugin instance complete, name:{}", alertPluginInstance.getInstanceName());
            return alertPluginInstance;
        }
        throw new ServiceException(Status.SAVE_ERROR);
    }

    /**
     * update alert plugin instance
     *
     * @param loginUser            login user
     * @param pluginInstanceId     plugin instance id
     * @param instanceName         instance name
     * @param pluginInstanceParams plugin instance params
     */

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Choose a unique instanceName
2. Query existing instances first and reuse/update the existing one instead of creating
3. In automation, catch the error and treat it as idempotent success or adopt the existing instance

Example fix

// before
alertPluginInstanceService.create(loginUser, pluginDefineId, "email-alert", params);
// after
if (alertPluginInstanceMapper.existInstanceName("email-alert") != Boolean.TRUE) {
    alertPluginInstanceService.create(loginUser, pluginDefineId, "email-alert", params);
}

if (alertPluginInstanceMapper.existInstanceName(instanceName) == Boolean.TRUE) {
    throw new IllegalArgumentException("instance name already exists: " + instanceName);
}

try {
    alertPluginInstanceService.create(loginUser, pluginDefineId, name, params);
} catch (ServiceException e) {
    if (e.getCode() == Status.PLUGIN_INSTANCE_ALREADY_EXISTS) { /* reuse existing */ }
    else throw e;
}

When it happens

Trigger: Calling POST /alert-plugin-instances with an instanceName matching an existing row in t_ds_alert_plugin_instance; the duplicate check runs before insert.

Common situations: Re-running provisioning scripts without uniqueness handling; two operators creating an instance named 'email-alert' concurrently; environment sync tools replaying instance definitions that already exist.

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

• REQUEST_PARAMS_NOT_VALID_ERROR
• ALERT_GROUP_EXIST
• REQUEST_PARAMS_NOT_VALID_ERROR
• 1400004
• The task instance is not under the project: {projectCode}

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