{"record":{"id":"128ec7ea94972112","repo":"elsa-workflows/elsa-core","slug":"workflow-definition-not-found-localworkflowclient","errorCode":null,"errorMessage":"Workflow definition not found.","messagePattern":"Workflow definition not found\\.","errorType":"exception","errorClass":"WorkflowDefinitionNotFoundException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs","lineNumber":218,"sourceCode":"        if (workflowInstance == null) throw new WorkflowInstanceNotFoundException(\"Workflow instance not found.\", WorkflowInstanceId);\n        return workflowInstance;\n    }\n\n    private Task<WorkflowInstance?> TryGetWorkflowInstanceAsync(CancellationToken cancellationToken)\n    {\n        return workflowInstanceManager.FindByIdAsync(WorkflowInstanceId, cancellationToken);\n    }\n\n    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowInstance workflowInstance, CancellationToken cancellationToken)\n    {\n        var handle = WorkflowDefinitionHandle.ByDefinitionVersionId(workflowInstance.DefinitionVersionId);\n        return await GetWorkflowGraphAsync(handle, cancellationToken);\n    }\n\n    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowDefinitionHandle definitionHandle, CancellationToken cancellationToken)\n    {\n        var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(definitionHandle, cancellationToken);\n        if (!result.WorkflowDefinitionExists) throw new WorkflowDefinitionNotFoundException(\"Workflow definition not found.\", definitionHandle);\n        if (!result.WorkflowGraphExists) throw new WorkflowMaterializerNotFoundException(result.WorkflowDefinition!.MaterializerName);\n        return result.WorkflowGraph!;\n    }\n}","sourceCodeStart":200,"sourceCodeEnd":222,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs#L200-L222","documentation":"LocalWorkflowClient.GetWorkflowGraphAsync resolves the workflow graph for a definition handle via workflowDefinitionService.TryFindWorkflowGraphAsync. When the result indicates the workflow definition itself does not exist (WorkflowDefinitionExists == false), it throws WorkflowDefinitionNotFoundException. This happens before any materialization is attempted.","triggerScenarios":"Invoking a LocalWorkflowClient operation that resolves the definition (e.g. creating a client for an instance whose definition was deleted, or starting/resuming with a WorkflowDefinitionHandle pointing at a non-existent definition ID/version).","commonSituations":"Definition deleted or unpublished after instances referencing it exist; resuming old instances whose definition version was removed; deploying to an environment whose definition store lacks the definition.","solutions":["Re-deploy/publish the workflow definition (and matching version) to the target environment.","Verify the definition handle (definition ID or version ID) is correct via the definitions management API.","For orphaned instances, delete or migrate them, or restore the definition version they reference.","Catch WorkflowDefinitionNotFoundException and surface a clear 'definition missing' message to operators."],"exampleFix":"// before\nvar client = workflowRuntime.CreateWorkflowClient(instanceId);\nawait client.ResumeAsync(...); // throws: definition not found\n\n// after\nvar handle = await workflowInstanceManager.FindDefinitionHandleAsync(instanceId, ct);\nvar definition = await workflowDefinitionService.FindAsync(handle, ct);\nif (definition == null)\n{\n    logger.LogError(\"Definition for instance {InstanceId} is missing; re-publish the workflow first.\", instanceId);\n    return;\n}\nawait client.ResumeAsync(...);","handlingStrategy":"validation","validationCode":"var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(handle, ct);\nif (!result.WorkflowDefinitionExists) throw new InvalidOperationException($\"Definition '{handle}' is not deployed to this environment.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    await client.ResumeAsync(ct);\n}\ncatch (WorkflowDefinitionNotFoundException ex)\n{\n    logger.LogError(ex, \"Referenced workflow definition is missing; re-publish it.\");\n}","preventionTips":["Deploy and publish definitions before running instances against them","Keep environments' definition stores in sync","Don't delete definition versions still referenced by instances"],"tags":["workflow","runtime","not-found","definition"],"backgroundTag":"resource-not-found","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}