{"record":{"id":"5aa58fa0660aca16","repo":"apache/dolphinscheduler","slug":"plugin-instance-already-exists","errorCode":"PLUGIN_INSTANCE_ALREADY_EXISTS","errorMessage":"PLUGIN_INSTANCE_ALREADY_EXISTS","messagePattern":"PLUGIN_INSTANCE_ALREADY_EXISTS","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/AlertPluginInstanceServiceImpl.java","lineNumber":111,"sourceCode":"     */\n    @Override\n    public AlertPluginInstance create(User loginUser,\n                                      int pluginDefineId,\n                                      String instanceName,\n                                      String pluginInstanceParams) {\n\n        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ALERT_PLUGIN_INSTANCE, ALERT_INSTANCE_CREATE)) {\n            throw new ServiceException(Status.USER_NO_OPERATION_PERM);\n        }\n\n        AlertPluginInstance alertPluginInstance = new AlertPluginInstance();\n        String paramsMapJson = parsePluginParamsMap(pluginInstanceParams);\n        alertPluginInstance.setPluginInstanceParams(paramsMapJson);\n        alertPluginInstance.setInstanceName(instanceName);\n        alertPluginInstance.setPluginDefineId(pluginDefineId);\n\n        if (alertPluginInstanceMapper.existInstanceName(alertPluginInstance.getInstanceName()) == Boolean.TRUE) {\n            throw new ServiceException(Status.PLUGIN_INSTANCE_ALREADY_EXISTS);\n        }\n\n        int i = alertPluginInstanceMapper.insert(alertPluginInstance);\n        if (i > 0) {\n            log.info(\"Create alert plugin instance complete, name:{}\", alertPluginInstance.getInstanceName());\n            return alertPluginInstance;\n        }\n        throw new ServiceException(Status.SAVE_ERROR);\n    }\n\n    /**\n     * update alert plugin instance\n     *\n     * @param loginUser            login user\n     * @param pluginInstanceId     plugin instance id\n     * @param instanceName         instance name\n     * @param pluginInstanceParams plugin instance params\n     */","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/AlertPluginInstanceServiceImpl.java#L93-L129","documentation":"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.","triggerScenarios":"Calling POST /alert-plugin-instances with an instanceName matching an existing row in t_ds_alert_plugin_instance; the duplicate check runs before insert.","commonSituations":"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.","solutions":["Choose a unique instanceName","Query existing instances first and reuse/update the existing one instead of creating","In automation, catch the error and treat it as idempotent success or adopt the existing instance"],"exampleFix":"// before\nalertPluginInstanceService.create(loginUser, pluginDefineId, \"email-alert\", params);\n// after\nif (alertPluginInstanceMapper.existInstanceName(\"email-alert\") != Boolean.TRUE) {\n    alertPluginInstanceService.create(loginUser, pluginDefineId, \"email-alert\", params);\n}","handlingStrategy":"validation","validationCode":"if (alertPluginInstanceMapper.existInstanceName(instanceName) == Boolean.TRUE) {\n    throw new IllegalArgumentException(\"instance name already exists: \" + instanceName);\n}","typeGuard":null,"tryCatchPattern":"try {\n    alertPluginInstanceService.create(loginUser, pluginDefineId, name, params);\n} catch (ServiceException e) {\n    if (e.getCode() == Status.PLUGIN_INSTANCE_ALREADY_EXISTS) { /* reuse existing */ }\n    else throw e;\n}","preventionTips":["Check instance name uniqueness before creating","Make provisioning scripts idempotent with generated suffixes","Adopt or update the existing instance instead of failing"],"tags":["duplicate-resource","validation","api"],"backgroundTag":"file-already-exists","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}