elsa-workflows/elsa-core · error · InvalidOperationException

A workflow definition handle must be provided.

Error message

A workflow definition handle must be provided.

What it means

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.

Solutions

1. Set request.WorkflowDefinitionHandle (e.g. via WorkflowDefinitionHandle.ByDefinitionId or version/published handle) before starting.
2. Or pass a fully built Workflow instance via request.Workflow when starting programmatically constructed workflows.
3. Check the mapping layer so the handle field from your API/DTO is carried into StartWorkflowRequest.

Example fix

// before
var request = new StartWorkflowRequest { Input = input };
// after
var request = new StartWorkflowRequest
{
    WorkflowDefinitionHandle = WorkflowDefinitionHandle.ByDefinitionId(definitionId, versionOptions),
    Input = input
};

if (request.Workflow == null && request.WorkflowDefinitionHandle == null)
    throw new ArgumentException("Provide either Workflow or WorkflowDefinitionHandle.");

try { await starter.StartWorkflowAsync(request); } catch (InvalidOperationException ex) when (ex.Message.Contains("workflow definition handle")) { return BadRequest("Specify a workflow definition handle."); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either ActivityTypeName or StimulusHash must be specified.
• The specified activity is not part of the workflow.
• Workflow definition not found.
• Drain already in progress; second invocation rejected
• Drain already completed in this generation; subsequent…

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/fdfbcf7291a1d478. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowStarter.cs:59

        var runWorkflowResponse = await workflowClient.CreateAndRunInstanceAsync(createWorkflowInstanceRequest, cancellationToken);
        return new()
        {
            CannotStart = false,
            WorkflowInstanceId = runWorkflowResponse.WorkflowInstanceId,
            Status = runWorkflowResponse.Status,
            SubStatus = runWorkflowResponse.SubStatus,
            Bookmarks = runWorkflowResponse.Bookmarks,
            Incidents = runWorkflowResponse.Incidents
        };
    }

    private async Task<Workflow> GetWorkflowAsync(StartWorkflowRequest request, CancellationToken cancellationToken)
    {
        if (request.Workflow != null)
            return request.Workflow;

        if (request.WorkflowDefinitionHandle == null)
            throw new InvalidOperationException("A workflow definition handle must be provided.");

        var workflowGraph = await workflowDefinitionService.FindWorkflowGraphAsync(request.WorkflowDefinitionHandle, cancellationToken);

        if (workflowGraph == null)
            throw new WorkflowGraphNotFoundException("Workflow definition not found.", request.WorkflowDefinitionHandle);

        return workflowGraph.Workflow;
    }
}

View on GitHub (pinned to fe9217bdfa)