elsa-workflows/elsa-core · error · WorkflowGraphNotFoundException

Workflow definition not found.

Error message

Workflow definition not found.

What it means

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.

Solutions

1. Verify the workflow definition exists and is published: query the definition store or management API for the definition ID and check its version.
2. Confirm the application connects to the same database/tenant where the definition was deployed.
3. If starting by definition ID and latest published version, ensure at least one version is published.
4. Catch WorkflowGraphNotFoundException around GetWorkflowAsync and handle missing-definition deployment (e.g. re-deploy the definition) before retrying.

Example fix

// before
var workflow = await starter.StartWorkflowAsync(new StartWorkflowRequest
{
    WorkflowDefinitionHandle = WorkflowDefinitionHandle.ForDefinitionId("order-process")
});

// after
var handle = WorkflowDefinitionHandle.ForDefinitionId("order-process");
var definition = await workflowDefinitionService.FindAsync(handle, cancellationToken);
if (definition == null)
{
    logger.LogError("Workflow definition 'order-process' is not deployed; deploying before starting.");
    await DeployDefinitionAsync();
}
var workflow = await starter.StartWorkflowAsync(new StartWorkflowRequest { WorkflowDefinitionHandle = handle });

var definition = await workflowDefinitionService.FindAsync(handle, ct);
if (definition == null) throw new InvalidOperationException($"Workflow definition '{handle.DefinitionId}' v{handle.Version} is not deployed.");

try
{
    var workflow = await starter.GetWorkflowAsync(request, ct);
}
catch (WorkflowGraphNotFoundException ex)
{
    logger.LogError(ex, "Workflow definition not found: {Handle}", request.WorkflowDefinitionHandle);
}

When it happens

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

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

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Workflow definition not found.
• Workflow instance 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/f5d097736c25b890. Report an issue: GitHub.

Appendix: source

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

            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)