{"record":{"id":"3543827bae50e605","repo":"apache/dolphinscheduler","slug":"failed-to-insert-plugin-definition-pluginname-s","errorCode":null,"errorMessage":"Failed to insert plugin definition, pluginName: %s, pluginType: %s","messagePattern":"Failed to insert plugin definition, pluginName: (.+?), pluginType: (.+?)","errorType":"exception","errorClass":"TaskPluginException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-dao/src/main/java/org/apache/dolphinscheduler/dao/PluginDao.java","lineNumber":58,"sourceCode":"\n    /**\n     * add or update plugin define\n     *\n     * @param pluginDefine new pluginDefine\n     * @return plugin id\n     */\n    public int addOrUpdatePluginDefine(@NonNull PluginDefine pluginDefine) {\n        requireNonNull(pluginDefine.getPluginName(), \"pluginName is null\");\n        requireNonNull(pluginDefine.getPluginType(), \"pluginType is null\");\n\n        PluginDefine currPluginDefine =\n                pluginDefineMapper.queryByNameAndType(pluginDefine.getPluginName(), pluginDefine.getPluginType());\n        if (currPluginDefine == null) {\n            try {\n                if (pluginDefineMapper.insert(pluginDefine) == 1 && pluginDefine.getId() != null) {\n                    return pluginDefine.getId();\n                }\n                throw new TaskPluginException(\n                        String.format(\"Failed to insert plugin definition, pluginName: %s, pluginType: %s\",\n                                pluginDefine.getPluginName(), pluginDefine.getPluginType()));\n            } catch (TaskPluginException ex) {\n                throw ex;\n            } catch (Exception ex) {\n                log.error(\"Insert plugin definition error, there may already exist a plugin\", ex);\n                currPluginDefine = pluginDefineMapper.queryByNameAndType(pluginDefine.getPluginName(),\n                        pluginDefine.getPluginType());\n                if (currPluginDefine == null) {\n                    throw new TaskPluginException(\n                            String.format(\"Failed to insert plugin definition, pluginName: %s, pluginType: %s\",\n                                    pluginDefine.getPluginName(), pluginDefine.getPluginType()));\n                }\n            }\n        }\n        if (!Objects.equals(currPluginDefine.getPluginParams(), pluginDefine.getPluginParams())) {\n            currPluginDefine.setUpdateTime(pluginDefine.getUpdateTime());\n            currPluginDefine.setPluginParams(pluginDefine.getPluginParams());","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-dao/src/main/java/org/apache/dolphinscheduler/dao/PluginDao.java#L40-L76","documentation":"PluginDao.addOrUpdatePluginDefine() inserts a new plugin define row when none exists by (pluginName, pluginType). If insert succeeds but no ID is generated (affected row count or generated key wrong), it throws TaskPluginException with this message. It indicates the plugin definition could not be persisted to the t_ds_plugin_define table.","triggerScenarios":"Installing/registering a plugin where pluginDefineMapper.insert() returns 1 but getId() is null (missing MyBatis useGeneratedKeys/keyProperty mapping), or insert returns != 1.","commonSituations":"Database without auto-increment support or misconfigured key generator; plugin JAR loaded twice at startup causing race conditions; DB constraint/connection issues during server bootstrap.","solutions":["Verify the PluginDefine MyBatis mapper has keyProperty=\"id\" useGeneratedKeys=\"true\" on the insert.","Check DB connectivity and that t_ds_plugin_define has a proper auto-increment primary key.","Look at the preceding log line 'Insert plugin definition error' for the real DB exception.","Ensure only one server instance initializes plugin defines at a time or rely on the retry path."],"exampleFix":"// before\nif (pluginDefineMapper.insert(pluginDefine) == 1 && pluginDefine.getId() != null) {\n// after (mapper XML)\n<insert id=\"insert\" useGeneratedKeys=\"true\" keyProperty=\"id\"> ... </insert>","handlingStrategy":"try-catch","validationCode":"PluginDefine existing = pluginDefineMapper.queryByNameAndType(name, type);\nif (existing != null) return existing.getId(); // avoid insert path","typeGuard":null,"tryCatchPattern":"try {\n    return pluginDao.addOrUpdatePluginDefine(define);\n} catch (TaskPluginException e) {\n    log.error(\"Plugin define persist failed: {}\", e.getMessage(), e);\n    throw e;\n}","preventionTips":["Keep MyBatis generated-key mapping (useGeneratedKeys/keyProperty) correct.","Confirm t_ds_plugin_define has an auto-increment PK in all environments.","Watch server startup logs for 'Insert plugin definition error'."],"tags":["database","plugin","dao"],"backgroundTag":"database-write-failed","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"}