elsa-workflows/elsa-core · error · WorkflowInstanceNotFoundException

Workflow instance not found.

Error message

Workflow instance not found.

What it means

LocalWorkflowClient.GetWorkflowInstanceAsync loads the workflow instance by the client's WorkflowInstanceId via the instance manager. When no instance with that ID exists, it throws WorkflowInstanceNotFoundException with 'Workflow instance not found.'. Elsa throws this for local (in-process) client operations that require an existing instance.

Solutions

1. Verify the workflow instance ID exists in the instance store (query by ID via the management API).
2. Use the TryGet-style/Find API first and handle a null result instead of the throwing path.
3. Check you are not confusing the instance ID with a correlation ID or workflow definition ID.
4. Confirm tenant/connection configuration matches where the instance was created.

Example fix

// before
var client = workflowRuntime.CreateWorkflowClient(instanceId);
await client.ExecuteCommandAsync(...); // throws if instance missing

// after
var instance = await workflowInstanceManager.FindByIdAsync(instanceId, ct);
if (instance == null)
{
    logger.LogWarning("Workflow instance {InstanceId} not found; skipping.", instanceId);
    return;
}
var client = workflowRuntime.CreateWorkflowClient(instanceId);
await client.ExecuteCommandAsync(...);

var instance = await workflowInstanceManager.FindByIdAsync(instanceId, ct);
if (instance == null)
{
    logger.LogWarning("Workflow instance {InstanceId} not found.", instanceId);
    return;
}

bool WorkflowInstanceExists(WorkflowInstance? instance) => instance is not null;

try
{
    await client.ExecuteCommandAsync(cmd, ct);
}
catch (WorkflowInstanceNotFoundException ex)
{
    logger.LogWarning(ex, "Instance {InstanceId} does not exist.", instanceId);
}

When it happens

Trigger: Any LocalWorkflowClient operation requiring the instance (e.g. CanExecuteBookmarkAsync, instance-scoped commands) where workflowInstanceManager.FindByIdAsync(WorkflowInstanceId) returns null because the ID does not exist or is not visible in the current tenant.

Common situations: Using an instance ID from a different database/environment; the instance was deleted (retention/cleanup) before the call; ID typo or copying the wrong field (e.g. correlation ID instead of instance ID); multi-tenant setup where the instance belongs to another tenant.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Workflow definition not found.
• Workflow definition not found.
• AlterationFaultCodes.PlanNotFound
• Activity type not found
• The memory block ' ' does not exist.

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

Appendix: source

Thrown at src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs:200

        var workflowGraph = await GetWorkflowGraphAsync(workflowDefinitionHandle, cancellationToken);

        var options = new WorkflowInstanceOptions
        {
            WorkflowInstanceId = WorkflowInstanceId,
            CorrelationId = request.CorrelationId,
            Name = request.Name,
            ParentWorkflowInstanceId = request.ParentId,
            Input = request.Input,
            Properties = request.Properties
        };

        return workflowInstanceManager.CreateWorkflowInstance(workflowGraph.Workflow, options);
    }

    private async Task<WorkflowInstance> GetWorkflowInstanceAsync(CancellationToken cancellationToken)
    {
        var workflowInstance = await TryGetWorkflowInstanceAsync(cancellationToken);
        if (workflowInstance == null) throw new WorkflowInstanceNotFoundException("Workflow instance not found.", WorkflowInstanceId);
        return workflowInstance;
    }

    private Task<WorkflowInstance?> TryGetWorkflowInstanceAsync(CancellationToken cancellationToken)
    {
        return workflowInstanceManager.FindByIdAsync(WorkflowInstanceId, cancellationToken);
    }

    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowInstance workflowInstance, CancellationToken cancellationToken)
    {
        var handle = WorkflowDefinitionHandle.ByDefinitionVersionId(workflowInstance.DefinitionVersionId);
        return await GetWorkflowGraphAsync(handle, cancellationToken);
    }

    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowDefinitionHandle definitionHandle, CancellationToken cancellationToken)
    {
        var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(definitionHandle, cancellationToken);
        if (!result.WorkflowDefinitionExists) throw new WorkflowDefinitionNotFoundException("Workflow definition not found.", definitionHandle);

View on GitHub (pinned to fe9217bdfa)