elsa-workflows/elsa-core · error · WorkflowDefinitionNotFoundException

Workflow definition not found.

Error message

Workflow definition not found.

What it means

LocalWorkflowClient.GetWorkflowGraphAsync resolves the workflow graph for a definition handle via workflowDefinitionService.TryFindWorkflowGraphAsync. When the result indicates the workflow definition itself does not exist (WorkflowDefinitionExists == false), it throws WorkflowDefinitionNotFoundException. This happens before any materialization is attempted.

Solutions

1. Re-deploy/publish the workflow definition (and matching version) to the target environment.
2. Verify the definition handle (definition ID or version ID) is correct via the definitions management API.
3. For orphaned instances, delete or migrate them, or restore the definition version they reference.
4. Catch WorkflowDefinitionNotFoundException and surface a clear 'definition missing' message to operators.

Example fix

// before
var client = workflowRuntime.CreateWorkflowClient(instanceId);
await client.ResumeAsync(...); // throws: definition not found

// after
var handle = await workflowInstanceManager.FindDefinitionHandleAsync(instanceId, ct);
var definition = await workflowDefinitionService.FindAsync(handle, ct);
if (definition == null)
{
    logger.LogError("Definition for instance {InstanceId} is missing; re-publish the workflow first.", instanceId);
    return;
}
await client.ResumeAsync(...);

var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(handle, ct);
if (!result.WorkflowDefinitionExists) throw new InvalidOperationException($"Definition '{handle}' is not deployed to this environment.");

try
{
    await client.ResumeAsync(ct);
}
catch (WorkflowDefinitionNotFoundException ex)
{
    logger.LogError(ex, "Referenced workflow definition is missing; re-publish it.");
}

When it happens

Trigger: Invoking a LocalWorkflowClient operation that resolves the definition (e.g. creating a client for an instance whose definition was deleted, or starting/resuming with a WorkflowDefinitionHandle pointing at a non-existent definition ID/version).

Common situations: Definition deleted or unpublished after instances referencing it exist; resuming old instances whose definition version was removed; deploying to an environment whose definition store lacks the definition.

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/128ec7ea94972112. Report an issue: GitHub.

Appendix: source

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

        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);
        if (!result.WorkflowGraphExists) throw new WorkflowMaterializerNotFoundException(result.WorkflowDefinition!.MaterializerName);
        return result.WorkflowGraph!;
    }
}

View on GitHub (pinned to fe9217bdfa)