apache/dolphinscheduler · error · ServiceException

MAIN_TABLE_USING_VERSION

MAIN_TABLE_USING_VERSION

Error message

MAIN_TABLE_USING_VERSION: the version is in use by the main table and cannot be deleted

What it means

Thrown when attempting to delete a workflow definition version that is still the current (main-table) version. Only historical versions recorded in the version/log table can be deleted; the active version must first be replaced by releasing a newer version.

Source

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

     * @param projectCode project code
     * @param code        workflow definition code
     * @param version     version number
     */
    @Override
    @Transactional
    public void deleteWorkflowDefinitionVersion(User loginUser,
                                                long projectCode,
                                                long code,
                                                int version) {
        projectService.checkHasProjectWritePermissionThrowException(loginUser, projectCode);

        WorkflowDefinition workflowDefinition = workflowDefinitionDao.queryByCode(code).orElse(null);
        if (workflowDefinition == null || projectCode != workflowDefinition.getProjectCode()) {
            throw new ServiceException(Status.WORKFLOW_DEFINITION_NOT_EXIST, code);
        }
        if (workflowDefinition.getVersion() == version) {
            log.warn("This version: {} of workflow: {} is the main version cannot delete by version", code, version);
            throw new ServiceException(Status.MAIN_TABLE_USING_VERSION);
        }
        // check whether there exist running workflow instance under the workflow definition
        List<WorkflowInstanceSummaryDto> workflowInstances = workflowInstanceService.queryByWorkflowCodeVersionStatus(
                code,
                version,
                WorkflowExecutionStatus.NOT_TERMINAL_STATES);
        if (CollectionUtils.isNotEmpty(workflowInstances)) {
            throw new ServiceException(Status.DELETE_WORKFLOW_DEFINITION_EXECUTING_FAIL, workflowInstances.size());
        }

        int deleteLog = workflowDefinitionLogMapper.deleteByWorkflowDefinitionCodeAndVersion(code, version);
        int deleteRelationLog = workflowTaskRelationLogMapper.deleteByCode(code, version);
        if (deleteLog == 0 || deleteRelationLog == 0) {
            throw new ServiceException(Status.DELETE_WORKFLOW_DEFINE_BY_CODE_ERROR);
        }
        log.info("Delete version: {} of workflow: {}, projectCode: {}", version, code, projectCode);

    }

View on GitHub (pinned to 02eac45a1b)

Solutions

Delete only non-current versions; list versions first and exclude workflowDefinition.getVersion().
If the current version must go away, release a new version (save/update the workflow) then delete the old one.
To remove the workflow entirely, use deleteWorkflowDefinitionByCode instead of delete-by-version.
Guard scripts: skip a version if it equals the definition's current version.

Example fix

// before
client.deleteVersion(projectCode, code, version); // version == current
// after
long current = workflowDefinitionDao.queryByCode(code).orElseThrow().getVersion();
if (version != current) client.deleteVersion(projectCode, code, version);

Defensive patterns

Strategy: validation

Validate before calling

WorkflowDefinition wf = workflowDefinitionDao.queryByCode(code).orElse(null);
boolean canDeleteVersion = wf != null && wf.getVersion() != version;
if (!canDeleteVersion) skipDelete(code, version);

Type guard

boolean isHistoricalVersion(WorkflowDefinition wf, long version) {
    return wf != null && wf.getVersion() != version;
}

Try / catch

try {
    service.deleteWorkflowDefinitionVersion(user, projectCode, code, version);
} catch (ServiceException e) {
    if (e.getCode() == Status.MAIN_TABLE_USING_VERSION.getCode()) {
        // version is current; release a new version or use delete-by-code instead
    } else throw e;
}

Prevention

Always fetch the definition's current version and exclude it from cleanup lists.
Use the version-history endpoint as the source of deletable versions.
For full removal use deleteWorkflowDefinitionByCode, not delete-by-version.

When it happens

Trigger: DELETE .../workflow-definition/{projectCode}/{code}/version/{version} where version equals workflowDefinition.getVersion() (the active version in t_ds_workflow_definition).

Common situations: Scripts cleaning up old versions that accidentally target the latest version; UI automation that resolves 'version' from the main table instead of from the version history list; deleting the only version a workflow ever had.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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