apache/dolphinscheduler · error · TaskPluginException
Failed to insert plugin definition, pluginName: %s, pluginTy
Error message
Failed to insert plugin definition, pluginName: %s, pluginType: %s
What it means
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.
Source
Thrown at dolphinscheduler-dao/src/main/java/org/apache/dolphinscheduler/dao/PluginDao.java:58
/**
* add or update plugin define
*
* @param pluginDefine new pluginDefine
* @return plugin id
*/
public int addOrUpdatePluginDefine(@NonNull PluginDefine pluginDefine) {
requireNonNull(pluginDefine.getPluginName(), "pluginName is null");
requireNonNull(pluginDefine.getPluginType(), "pluginType is null");
PluginDefine currPluginDefine =
pluginDefineMapper.queryByNameAndType(pluginDefine.getPluginName(), pluginDefine.getPluginType());
if (currPluginDefine == null) {
try {
if (pluginDefineMapper.insert(pluginDefine) == 1 && pluginDefine.getId() != null) {
return pluginDefine.getId();
}
throw new TaskPluginException(
String.format("Failed to insert plugin definition, pluginName: %s, pluginType: %s",
pluginDefine.getPluginName(), pluginDefine.getPluginType()));
} catch (TaskPluginException ex) {
throw ex;
} catch (Exception ex) {
log.error("Insert plugin definition error, there may already exist a plugin", ex);
currPluginDefine = pluginDefineMapper.queryByNameAndType(pluginDefine.getPluginName(),
pluginDefine.getPluginType());
if (currPluginDefine == null) {
throw new TaskPluginException(
String.format("Failed to insert plugin definition, pluginName: %s, pluginType: %s",
pluginDefine.getPluginName(), pluginDefine.getPluginType()));
}
}
}
if (!Objects.equals(currPluginDefine.getPluginParams(), pluginDefine.getPluginParams())) {
currPluginDefine.setUpdateTime(pluginDefine.getUpdateTime());
currPluginDefine.setPluginParams(pluginDefine.getPluginParams());View on GitHub (pinned to 02eac45a1b)
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.
Example fix
// before
if (pluginDefineMapper.insert(pluginDefine) == 1 && pluginDefine.getId() != null) {
// after (mapper XML)
<insert id="insert" useGeneratedKeys="true" keyProperty="id"> ... </insert> Defensive patterns
Strategy: try-catch
Validate before calling
PluginDefine existing = pluginDefineMapper.queryByNameAndType(name, type); if (existing != null) return existing.getId(); // avoid insert path
Try / catch
try {
return pluginDao.addOrUpdatePluginDefine(define);
} catch (TaskPluginException e) {
log.error("Plugin define persist failed: {}", e.getMessage(), e);
throw e;
} Prevention
- 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'.
When it happens
Trigger: Installing/registering a plugin where pluginDefineMapper.insert() returns 1 but getId() is null (missing MyBatis useGeneratedKeys/keyProperty mapping), or insert returns != 1.
Common situations: 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.
Related errors
AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06).
Data as JSON: /api/errors/3543827bae50e605.
Report an issue: GitHub.