apache/dolphinscheduler · error · IllegalStateException

Workflow definition not found: <workflowDefinitionCode> vers

Error message

Workflow definition not found: <workflowDefinitionCode> version: <workflowDefinitionVersion>

What it means

Thrown during workflow triggering when the requested workflow definition (by code and version) cannot be found in the definition log table. The master resolves the exact published snapshot (code + version) before constructing the trigger command; if the snapshot was deleted, unpublished, or the version never existed, the trigger cannot proceed and an IllegalStateException is raised.

Source

Thrown at dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/workflow/trigger/AbstractWorkflowInstanceTrigger.java:62

    @Autowired
    private CommandDao commandDao;

    @Autowired
    protected SerialCommandDao serialCommandDao;

    @Autowired
    protected WorkflowDefinitionLogDao workflowDefinitionLogDao;

    @Override
    @Transactional
    public TriggerResponse triggerWorkflow(final TriggerRequest triggerRequest) {
        final WorkflowInstance workflowInstance = constructWorkflowInstance(triggerRequest);
        final Long workflowDefinitionCode = workflowInstance.getWorkflowDefinitionCode();
        final int workflowDefinitionVersion = workflowInstance.getWorkflowDefinitionVersion();
        final WorkflowDefinitionLog workflowDefinition = workflowDefinitionLogDao.queryByDefinitionCodeAndVersion(
                workflowDefinitionCode, workflowDefinitionVersion);
        if (workflowDefinition == null) {
            throw new IllegalStateException(
                    "Workflow definition not found: " + workflowDefinitionCode + " version: "
                            + workflowDefinitionVersion);
        }
        final Command command = constructTriggerCommand(triggerRequest, workflowInstance);
        if (workflowDefinition.getExecutionType() == WorkflowExecutionTypeEnum.PARALLEL) {
            workflowInstanceDao.updateById(workflowInstance);
            commandDao.insert(command);
        } else {
            workflowInstance.setState(WorkflowExecutionStatus.SERIAL_WAIT);
            workflowInstanceDao.updateById(workflowInstance);
            serialCommandDao.insert(SerialCommandDto.newSerialCommand(command).toEntity());
        }

        return onTriggerSuccess(workflowInstance);
    }

    // todo: 使用WorkflowInstanceConstructor封装
    protected abstract WorkflowInstance constructWorkflowInstance(final TriggerRequest triggerRequest);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Confirm the code/version in t_ds_workflow_definition_log: SELECT * WHERE code=? AND version=?; re-publish the workflow if missing.
2. Delete or correct the stale schedule/complement/retry reference pointing to the deleted version.
3. Use the current version from t_ds_workflow_definition instead of a hardcoded version when calling trigger APIs.
4. Restore the definition-log row from backup or re-import the workflow JSON if the deletion was accidental.

Example fix

// before
master.triggerWorkflow(WorkflowTriggerRequest.of(code, oldVersion));
// after
WorkflowDefinition latest = queryLatestDefinition(code);
master.triggerWorkflow(WorkflowTriggerRequest.of(code, latest.getVersion()));

WorkflowDefinitionLog def = workflowDefinitionLogDao.queryByDefinitionCodeAndVersion(code, version);
if (def == null) {
    throw new IllegalArgumentException("Definition not found: " + code + " v" + version);
}
// safe to trigger

boolean definitionExists(long code, int version) {
    return workflowDefinitionLogDao.queryByDefinitionCodeAndVersion(code, version) != null;
}

try {
    triggerResponse = master.triggerWorkflow(request);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Workflow definition not found")) {
        log.error("Stale definition code/version: {}", e.getMessage());
        // refresh version or remove stale schedule
    }
}

When it happens

Trigger: Calling any trigger API (schedule, complement, retry, fault-tolerant trigger built on AbstractWorkflowInstanceTrigger) with a workflowDefinitionCode/version pair absent from t_ds_workflow_definition_log — e.g. querying a stale version after the definition was re-versioned or deleted.

Common situations: Workflow was deleted or offline while schedules/complements still reference it; metadata cleanup removed old definition-log rows; replica/master DB out of sync; API caller hardcoded an outdated version number.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Workflow instance not found: <workflowInstanceId>
• 120033
• Can not find any datasource by name %s
• Can not find valid workflow by name %s
• Can not find valid project by name %s

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