What causes "Workflow instance not found: " in apache/dolphinscheduler?

Verify the row exists: SELECT * FROM t_ds_workflow_instance WHERE id=?; if absent, re-trigger the workflow to get a fresh instance id.

apache/dolphinscheduler · error · IllegalStateException

Workflow instance not found: <workflowInstanceId>

Error message

Workflow instance not found: <workflowInstanceId>

What it means

A protected lookup helper on AbstractWorkflowInstanceTrigger that loads a WorkflowInstance by id and throws IllegalStateException when the DAO returns null. It is used by trigger subclasses (workflowInstance, getId, getName, status queries, finalize actions); a missing row means the instance was deleted or never committed, so the trigger cannot operate on it.

Source

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

            serialCommandDao.insert(SerialCommandDto.newSerialCommand(command).toEntity());
        }

        return onTriggerSuccess(workflowInstance);
    }

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

    // todo: 使用CommandConstructor封装
    protected abstract Command constructTriggerCommand(final TriggerRequest triggerRequest,
                                                       final WorkflowInstance workflowInstance);

    protected abstract TriggerResponse onTriggerSuccess(final WorkflowInstance workflowInstance);

    protected WorkflowInstance getWorkflowInstance(final Integer workflowInstanceId) {
        final WorkflowInstance workflowInstance = workflowInstanceDao.queryById(workflowInstanceId);
        if (workflowInstance == null) {
            throw new IllegalStateException("Workflow instance not found: " + workflowInstanceId);
        }
        return workflowInstance;
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

Verify the row exists: SELECT * FROM t_ds_workflow_instance WHERE id=?; if absent, re-trigger the workflow to get a fresh instance id.
Exclude recently purged instances from retries/finalization — treat a null lookup as terminal and skip instead of throwing up the stack.
Check DB replication/cleanup job timing if the id existed moments before; widen retention or re-point reads at the primary.
Validate the caller is using ids from the same environment/database, not stale or cross-env ids.

Example fix

// before
WorkflowInstance instance = workflowInstanceDao.queryById(id);
runFinalize(instance); // NPE / IllegalStateException if null
// after
WorkflowInstance instance = workflowInstanceDao.queryById(id);
if (instance == null) {
    log.warn("Workflow instance {} already purged, skipping finalize", id);
    return;
}
runFinalize(instance);

Defensive patterns

Strategy: validation

Validate before calling

WorkflowInstance inst = workflowInstanceDao.queryById(instanceId);
if (inst == null) {
    log.warn("Workflow instance {} missing, skipping", instanceId);
    return;
}

Type guard

Optional<WorkflowInstance> findInstance(int id) {
    return Optional.ofNullable(workflowInstanceDao.queryById(id));
}

Try / catch

try {
    WorkflowInstance inst = getWorkflowInstance(instanceId);
    // proceed
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Workflow instance not found")) {
        log.warn("Instance {} purged or never committed", instanceId);
    }
}

Prevention

Don't retain instance ids across history-cleanup windows or DB resets
Use ids returned by the same environment's trigger response
Account for replica lag — query the primary right after triggering
Treat missing instances as terminal in retry/finalize logic instead of retrying

When it happens

Trigger: Calling getWorkflowInstance(workflowInstanceId) — directly or via workflowInstance()/getName()/workflowExecutionStatus()/finalizeEventAction — with an id absent from t_ds_workflow_instance (instance purged by cleanup, DB replication lag, or an id from a failed/rolled-back trigger).

Common situations: History cleanup job deleted the instance while a retry/logic resource still references it; caller caches an instance id across a database reset; read replica lag right after triggering; passing an id from a different environment's database.

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

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