{"record":{"id":"f5d097736c25b890","repo":"elsa-workflows/elsa-core","slug":"workflow-definition-not-found","errorCode":null,"errorMessage":"Workflow definition not found.","messagePattern":"Workflow definition not found\\.","errorType":"exception","errorClass":"WorkflowGraphNotFoundException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowStarter.cs","lineNumber":64,"sourceCode":"            Status = runWorkflowResponse.Status,\n            SubStatus = runWorkflowResponse.SubStatus,\n            Bookmarks = runWorkflowResponse.Bookmarks,\n            Incidents = runWorkflowResponse.Incidents\n        };\n    }\n\n    private async Task<Workflow> GetWorkflowAsync(StartWorkflowRequest request, CancellationToken cancellationToken)\n    {\n        if (request.Workflow != null)\n            return request.Workflow;\n\n        if (request.WorkflowDefinitionHandle == null)\n            throw new InvalidOperationException(\"A workflow definition handle must be provided.\");\n\n        var workflowGraph = await workflowDefinitionService.FindWorkflowGraphAsync(request.WorkflowDefinitionHandle, cancellationToken);\n\n        if (workflowGraph == null)\n            throw new WorkflowGraphNotFoundException(\"Workflow definition not found.\", request.WorkflowDefinitionHandle);\n\n        return workflowGraph.Workflow;\n    }\n}","sourceCodeStart":46,"sourceCodeEnd":68,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowStarter.cs#L46-L68","documentation":"DefaultWorkflowStarter.GetWorkflowAsync resolves a workflow graph from the provided workflow definition handle. When the definition service returns no graph, it throws WorkflowGraphNotFoundException with the message 'Workflow definition not found.'. Elsa throws this because the requested definition (by ID/version or by definition-version ID) does not exist in the configured definition store.","triggerScenarios":"Calling IWorkflowStarter/GetWorkflowAsync (or StartWorkflowAsync paths) with a WorkflowDefinitionHandle whose definition ID, version, or version ID is not present in the workflow definition store, or whose version is unpublished/unavailable in the current tenant.","commonSituations":"Definition ID typo or definition deleted after being referenced; referring to an older version number that was never published; running against a different database/tenant than where the definition was deployed; using by-definition-id handles with only published versions while the definition is still a draft.","solutions":["Verify the workflow definition exists and is published: query the definition store or management API for the definition ID and check its version.","Confirm the application connects to the same database/tenant where the definition was deployed.","If starting by definition ID and latest published version, ensure at least one version is published.","Catch WorkflowGraphNotFoundException around GetWorkflowAsync and handle missing-definition deployment (e.g. re-deploy the definition) before retrying."],"exampleFix":"// before\nvar workflow = await starter.StartWorkflowAsync(new StartWorkflowRequest\n{\n    WorkflowDefinitionHandle = WorkflowDefinitionHandle.ForDefinitionId(\"order-process\")\n});\n\n// after\nvar handle = WorkflowDefinitionHandle.ForDefinitionId(\"order-process\");\nvar definition = await workflowDefinitionService.FindAsync(handle, cancellationToken);\nif (definition == null)\n{\n    logger.LogError(\"Workflow definition 'order-process' is not deployed; deploying before starting.\");\n    await DeployDefinitionAsync();\n}\nvar workflow = await starter.StartWorkflowAsync(new StartWorkflowRequest { WorkflowDefinitionHandle = handle });","handlingStrategy":"validation","validationCode":"var definition = await workflowDefinitionService.FindAsync(handle, ct);\nif (definition == null) throw new InvalidOperationException($\"Workflow definition '{handle.DefinitionId}' v{handle.Version} is not deployed.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var workflow = await starter.GetWorkflowAsync(request, ct);\n}\ncatch (WorkflowGraphNotFoundException ex)\n{\n    logger.LogError(ex, \"Workflow definition not found: {Handle}\", request.WorkflowDefinitionHandle);\n}","preventionTips":["Verify definition ID/version exists before starting workflows","Keep definition deployment and consumption in the same environment/tenant","Publish definitions before referencing them"],"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-15T23:17:13.987Z"}