What causes "Create workflow definition log error" in apache/dolphinscheduler?

Verify the relational database is writable and the t_ds_workflow_definition_log schema matches your version (run/verify upgrade migrations)

apache/dolphinscheduler · error

10201

10201

Error message

Create workflow definition log error

What it means

CREATE_WORKFLOW_DEFINITION_LOG_ERROR (10201) represents a failure to create a WorkflowDefinitionLog record - the versioned history row written into t_ds_workflow_definition_log whenever a workflow definition is saved, updated, or released. Every definition change inserts a snapshot log row so the scheduler can resolve which version a workflow instance ran on; when that insert fails (returned rows != 1) the API surfaces this status. In the current codebase the insert lives in ProcessServiceImpl.java:533 (saveWorkflowDefinitionLog) and this enum is largely a legacy status kept for API compatibility.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/enums/Status.java:252

            "未指定当前登录用户的租户"),
    REVOKE_PROJECT_ERROR(10182, "revoke project error", "撤销项目授权错误"),
    QUERY_AUTHORIZED_USER(10183, "query authorized user error", "查询拥有项目权限的用户错误"),
    PROJECT_NOT_EXIST(10190, "This project was not found. Please refresh page.", "该项目不存在,请刷新页面"),
    TASK_INSTANCE_HOST_IS_NULL(10191, "task instance host is null", "任务实例host为空"),
    QUERY_EXECUTING_WORKFLOW_ERROR(10192, "query executing workflow error", "查询运行的工作流实例错误"),
    DELETE_WORKFLOW_DEFINITION_USE_BY_OTHER_FAIL(10193,
            "delete workflow definition fail, cause used by other tasks: {0}",
            "删除工作流定义失败，被其他任务引用：{0}"),
    DELETE_TASK_USE_BY_OTHER_FAIL(10194, "delete task {0} fail, the reason is that used by other tasks: {1}",
            "删除任务 {0} 失败，被其他任务引用：{1}"),
    TASK_WITH_DEPENDENT_ERROR(10195, "task used in other tasks", "删除被其他任务引用"),
    TASK_SAVEPOINT_ERROR(10196, "task savepoint error", "任务实例savepoint错误"),
    TASK_STOP_ERROR(10197, "task stop error", "任务实例停止错误"),
    TASK_NAME_DUPLICATE_ERROR(10198, "task name {0} duplicate error", "同一个工作流中任务名称 {0} 重复"),
    LIST_TASK_TYPE_ERROR(10200, "list task type error", "查询任务类型列表错误"),
    DELETE_TASK_TYPE_ERROR(10200, "delete task type error", "删除任务类型错误"),
    ADD_TASK_TYPE_ERROR(10200, "add task type error", "添加任务类型错误"),
    CREATE_WORKFLOW_DEFINITION_LOG_ERROR(10201, "Create workflow definition log error",
            "创建 workflow definition log 对象失败"),
    PARSE_SCHEDULE_PARAM_ERROR(10202, "Parse schedule parameter error, {0}", "解析 schedule 参数错误, {0}"),
    SCHEDULE_NOT_EXISTS(10203, "schedule {0} does not exist", "调度 id {0} 不存在"),
    SCHEDULE_ALREADY_EXISTS(10204, "workflow {0} schedule {1} already exist, please update or delete it",
            "工作流 {0} 的定时 {1} 已经存在，请更新或删除"),
    QUERY_TASK_INSTANCE_ERROR(10205, "query task instance error", "查询任务实例错误"),
    EXECUTE_NOT_DEFINE_TASK(10206, "please save and try again",
            "请先保存后再执行"),

    DELETE_QUEUE_BY_ID_ERROR(10307, "delete queue by id error", "删除队列错误"),
    DELETE_QUEUE_BY_ID_FAIL_USERS(10308, "delete queue by id fail, for there are {0} users using it",
            "删除队列失败，有[{0}]个用户正在使用"),
    DELETE_TENANT_BY_ID_FAIL_TENANTS(10309, "delete queue by id fail, for there are {0} tenants using it",
            "删除队列失败，有[{0}]个租户正在使用"),
    START_NODE_NOT_EXIST_IN_LAST_WORKFLOW(10207, "this node {0} does not exist in the latest workflow definition",
            "该节点 {0} 不存在于最新的流程定义中"),
    LIST_AZURE_DATA_FACTORY_ERROR(10208, "list azure data factory error", "查询AZURE数据工厂列表错误"),
    LIST_AZURE_RESOURCE_GROUP_ERROR(10209, "list azure resource group error", "查询AZURE资源组列表错误"),

View on GitHub (pinned to 02eac45a1b)

Solutions

Verify the relational database is writable and the t_ds_workflow_definition_log schema matches your version (run/verify upgrade migrations)
Retry saving the workflow definition - transient DB failures or lock contention often resolve on retry
Check api-server logs for the underlying SQLException/MapperException wrapped by this status
Reduce concurrent edits to the same workflow definition and re-save
If the table has grown huge, archive old version rows and re-attempt the save

Example fix

// before: ignoring insert result of the definition log row
int insertLog = workflowDefinitionLogMapper.insert(workflowDefinitionLog);
// after: fail fast and surface CREATE_WORKFLOW_DEFINITION_LOG_ERROR
int insertLog = workflowDefinitionLogMapper.insert(workflowDefinitionLog);
if (insertLog != 1) {
    throw new ServiceException(Status.CREATE_WORKFLOW_DEFINITION_LOG_ERROR);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check DB writability and schema presence before saving a workflow definition
try (Connection c = dataSource.getConnection()) {
    DatabaseMetaData md = c.getMetaData();
    if (!md.getTables(null, null, "t_ds_workflow_definition_log", null).next()) {
        throw new IllegalStateException("missing t_ds_workflow_definition_log - run upgrade migrations");
    }
}

Type guard

static boolean definitionPersistable(WorkflowDefinition d) {
    return d != null && d.getCode() != 0 && StringUtils.isNotBlank(d.getName()) && d.getProjectCode() != 0;
}

Try / catch

try {
    Map<String, Object> result = workflowDefinitionService.createWorkflowDefinition(loginUser, projectCode, params);
} catch (ServiceException e) {
    if (e.getCode() == 10201) {
        // definition-log insert failed: check DB health and retry the save
        log.error("workflow definition log insert failed", e);
    } else {
        throw e;
    }
}

Prevention

Apply all schema upgrade migrations before starting a new api-server version
Avoid two users editing the same workflow definition concurrently; use the version history UI to reconcile
Monitor metadata DB disk space and lock waits
Keep the *_log tables pruned/archived so inserts stay fast

When it happens

Trigger: Saving or updating a workflow definition (POST/PUT /dolphinscheduler/workflow-definition... style calls in older releases) where the insert into t_ds_workflow_definition_log returns 0 or throws; database connection failure or constraint violation during the definition-version insert; transaction rollback while persisting the definition snapshot.

Common situations: Database out of disk space or t_ds_workflow_definition_log table locked/full during heavy definition churn; upgrading DolphinScheduler versions where schema migration for the *_log tables was not applied; duplicate version rows from concurrent edits of the same workflow by two users.

Related errors

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