{"record":{"id":"fdfbcf7291a1d478","repo":"elsa-workflows/elsa-core","slug":"a-workflow-definition-handle-must-be-provided","errorCode":null,"errorMessage":"A workflow definition handle must be provided.","messagePattern":"A workflow definition handle must be provided\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowStarter.cs","lineNumber":59,"sourceCode":"        var runWorkflowResponse = await workflowClient.CreateAndRunInstanceAsync(createWorkflowInstanceRequest, cancellationToken);\n        return new()\n        {\n            CannotStart = false,\n            WorkflowInstanceId = runWorkflowResponse.WorkflowInstanceId,\n            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":41,"sourceCodeEnd":68,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowStarter.cs#L41-L68","documentation":"DefaultWorkflowStarter.GetWorkflowAsync resolves the workflow to start from either an inline Workflow on the request or a WorkflowDefinitionHandle. If the request carries neither — no inline workflow and no handle — it throws InvalidOperationException because there is nothing to start.","triggerScenarios":"Calling IWorkflowStarter/StartWorkflowRequest with only e.g. input or correlation ID set, leaving Workflow and WorkflowDefinitionHandle both null; a caller constructing StartWorkflowRequest manually and forgetting the handle.","commonSituations":"Custom host code starting workflows by definition ID but forgetting to wrap it in a workflow definition handle; API layers dropping the handle field during mapping; refactors after upgrading Elsa that changed the request shape.","solutions":["Set request.WorkflowDefinitionHandle (e.g. via WorkflowDefinitionHandle.ByDefinitionId or version/published handle) before starting.","Or pass a fully built Workflow instance via request.Workflow when starting programmatically constructed workflows.","Check the mapping layer so the handle field from your API/DTO is carried into StartWorkflowRequest."],"exampleFix":"// before\nvar request = new StartWorkflowRequest { Input = input };\n// after\nvar request = new StartWorkflowRequest\n{\n    WorkflowDefinitionHandle = WorkflowDefinitionHandle.ByDefinitionId(definitionId, versionOptions),\n    Input = input\n};","handlingStrategy":"validation","validationCode":"if (request.Workflow == null && request.WorkflowDefinitionHandle == null)\n    throw new ArgumentException(\"Provide either Workflow or WorkflowDefinitionHandle.\");","typeGuard":null,"tryCatchPattern":"try { await starter.StartWorkflowAsync(request); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"workflow definition handle\")) { return BadRequest(\"Specify a workflow definition handle.\"); }","preventionTips":["Always set WorkflowDefinitionHandle when not passing an inline Workflow","Use factory helpers (WorkflowDefinitionHandle.ByDefinitionId/ByDefinitionVersionId) to build handles","Map API DTO handle fields into StartWorkflowRequest explicitly","Add unit tests asserting requests carry a workflow source"],"tags":["workflow-start","missing-required-argument","runtime"],"backgroundTag":"missing-required-argument","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"}