{"record":{"id":"d4c21ce77bb610da","repo":"apache/dolphinscheduler","slug":"workflow-instance-not-found-workflowinstanceid","errorCode":null,"errorMessage":"Workflow instance not found: <workflowInstanceId>","messagePattern":"Workflow instance not found: <workflowInstanceId>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/workflow/trigger/AbstractWorkflowInstanceTrigger.java","lineNumber":91,"sourceCode":"            serialCommandDao.insert(SerialCommandDto.newSerialCommand(command).toEntity());\n        }\n\n        return onTriggerSuccess(workflowInstance);\n    }\n\n    // todo: 使用WorkflowInstanceConstructor封装\n    protected abstract WorkflowInstance constructWorkflowInstance(final TriggerRequest triggerRequest);\n\n    // todo: 使用CommandConstructor封装\n    protected abstract Command constructTriggerCommand(final TriggerRequest triggerRequest,\n                                                       final WorkflowInstance workflowInstance);\n\n    protected abstract TriggerResponse onTriggerSuccess(final WorkflowInstance workflowInstance);\n\n    protected WorkflowInstance getWorkflowInstance(final Integer workflowInstanceId) {\n        final WorkflowInstance workflowInstance = workflowInstanceDao.queryById(workflowInstanceId);\n        if (workflowInstance == null) {\n            throw new IllegalStateException(\"Workflow instance not found: \" + workflowInstanceId);\n        }\n        return workflowInstance;\n    }\n\n}\n","sourceCodeStart":73,"sourceCodeEnd":97,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/workflow/trigger/AbstractWorkflowInstanceTrigger.java#L73-L97","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nWorkflowInstance instance = workflowInstanceDao.queryById(id);\nrunFinalize(instance); // NPE / IllegalStateException if null\n// after\nWorkflowInstance instance = workflowInstanceDao.queryById(id);\nif (instance == null) {\n    log.warn(\"Workflow instance {} already purged, skipping finalize\", id);\n    return;\n}\nrunFinalize(instance);","handlingStrategy":"validation","validationCode":"WorkflowInstance inst = workflowInstanceDao.queryById(instanceId);\nif (inst == null) {\n    log.warn(\"Workflow instance {} missing, skipping\", instanceId);\n    return;\n}","typeGuard":"Optional<WorkflowInstance> findInstance(int id) {\n    return Optional.ofNullable(workflowInstanceDao.queryById(id));\n}","tryCatchPattern":"try {\n    WorkflowInstance inst = getWorkflowInstance(instanceId);\n    // proceed\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Workflow instance not found\")) {\n        log.warn(\"Instance {} purged or never committed\", instanceId);\n    }\n}","preventionTips":["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"],"tags":["workflow-trigger","not-found","instance","database"],"backgroundTag":"entity-not-found","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}