What causes "create workflow definition error" in apache/dolphinscheduler?

Inspect API server logs for the exception inside saveWorkflowDefine; fix the underlying DB issue (connection, space, constraints).

apache/dolphinscheduler · error · ServiceException

10105

10105

Error message

create workflow definition error

What it means

Thrown by createDagDefine when processService.saveWorkflowDefine returns insertVersion == 0, i.e. the workflow definition (and its initial version log) could not be persisted. The creation aborts before task relations are saved.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkflowDefinitionServiceImpl.java:294

                                                 List<WorkflowTaskRelationLog> taskRelationList,
                                                 WorkflowDefinition workflowDefinition,
                                                 List<TaskDefinitionLog> taskDefinitionLogs) {
        taskDatasourcePermissionChecker.checkPermission(loginUser, taskDefinitionLogs);
        taskSubWorkflowPermissionChecker.checkPermission(loginUser, taskDefinitionLogs);
        int saveTaskResult = processService.saveTaskDefine(loginUser, workflowDefinition.getProjectCode(),
                taskDefinitionLogs, Boolean.TRUE);
        if (saveTaskResult == Constants.EXIT_CODE_SUCCESS) {
            log.info("The task has not changed, so skip");
        }
        if (saveTaskResult == Constants.DEFINITION_FAILURE) {
            log.error("Save task definition error.");
            throw new ServiceException(Status.CREATE_TASK_DEFINITION_ERROR);
        }
        int insertVersion =
                processService.saveWorkflowDefine(loginUser, workflowDefinition, Boolean.TRUE, Boolean.TRUE);
        if (insertVersion == 0) {
            log.error("Save workflow definition error, workflowDefinitionCode:{}.", workflowDefinition.getCode());
            throw new ServiceException(Status.CREATE_WORKFLOW_DEFINITION_ERROR);
        }
        log.info("Save workflow definition complete, workflowDefinitionCode:{}, workflowDefinitionVersion:{}.",
                workflowDefinition.getCode(), insertVersion);
        workflowDefinition.setVersion(insertVersion);
        int insertResult = processService.saveTaskRelation(loginUser, workflowDefinition.getProjectCode(),
                workflowDefinition.getCode(),
                insertVersion, taskRelationList, taskDefinitionLogs, Boolean.TRUE);
        if (insertResult != Constants.EXIT_CODE_SUCCESS) {
            log.error(
                    "Save workflow task relations error, projectCode:{}, workflowDefinitionCode:{}, workflowDefinitionVersion:{}.",
                    workflowDefinition.getProjectCode(), workflowDefinition.getCode(), insertVersion);
            throw new ServiceException(Status.CREATE_WORKFLOW_TASK_RELATION_ERROR);
        }
        log.info(
                "Save workflow task relations complete, projectCode:{}, workflowDefinitionCode:{}, workflowDefinitionVersion:{}.",
                workflowDefinition.getProjectCode(), workflowDefinition.getCode(), insertVersion);

        saveWorkflowLineage(workflowDefinition.getProjectCode(), workflowDefinition.getCode(),

View on GitHub (pinned to 02eac45a1b)

Solutions

Inspect API server logs for the exception inside saveWorkflowDefine; fix the underlying DB issue (connection, space, constraints).
Retry workflow creation after the database is healthy; confirm no orphan rows block the insert.
Verify request fields (name, locations, taskRelationJson) are valid so the definition row inserts cleanly.

Example fix

// before: DB down, create fails
POST /workflow-definition  -> 10105
// after: ensure DB reachable and retry
check dolphinscheduler database connectivity/health, then re-issue createWorkflowDefinition

Defensive patterns

Strategy: retry

Validate before calling

// pre-check DB reachability
boolean dbHealthy = checkDataSource();

Try / catch

try {
    workflowDefinitionService.createWorkflowDefinition(...);
} catch (ServiceException e) {
    if (e.getCode() == 10105) { /* fix DB issue then retry with backoff */ }
    else throw e;
}

Prevention

Monitor database connectivity and disk space for the DolphinScheduler schema.
Retry transient DB failures with backoff in automation.
Verify request payloads are complete before create calls to avoid partial-failure states.

When it happens

Trigger: createWorkflowDefinition/doBatchOperateWorkflowDefinition calls saveWorkflowDefine after task definitions saved OK, but the DB insert of the workflow definition row or its definition log fails/returns 0.

Common situations: Database connectivity or storage capacity problems; unique constraint collisions on workflow code; timezone/clock or transaction rollback issues; corrupted input causing silent failure inside saveWorkflowDefine.

Related errors

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