elsa-workflows/elsa-core · error · Exception

Workflow definition with ID

Error message

Workflow definition with ID '{definitionId}' not found

What it means

The alterations (error-correction) feature dispatches an 'ExecuteAlterationPlan' workflow by its well-known definition ID. Before dispatching a submitted alteration plan, DefaultAlterationPlanScheduler resolves the published workflow graph for that definition and throws when none exists. This means the alterations infrastructure workflow is absent or not published in the target store.

Solutions

1. Ensure the Elsa.Alterations module and its features are registered so ExecuteAlterationPlanWorkflow is registered and published
2. Publish the ExecuteAlterationPlan workflow definition in the target database
3. Verify you are pointed at the correct database/tenant containing the published definition
4. Check VersionOptions.Published is satisfied (a draft-only version is not enough)

Example fix

// before
services.AddElsa(elsa => elsa.AddActivities<Elsa.Alterations.Activities>()); // alterations workflow features missing
// after
services.AddElsa(elsa => elsa.AddAlterations().AddActivitiesFrom<Elsa.Alterations.Activities>()); // registers & publishes plan workflow

var graph = await workflowDefinitionService.FindWorkflowGraphAsync(
    ExecuteAlterationWorkflow.WorkflowDefinitionId, VersionOptions.Published, ct);
if (graph == null)
    throw new InvalidOperationException("ExecuteAlterationPlan workflow is not published in this environment");

bool CanSubmitAlterations(IWorkflowDefinitionService svc, CancellationToken ct) => svc.FindWorkflowGraphAsync(ExecuteAlterationPlanWorkflow.WorkflowDefinitionId, VersionOptions.Published, ct).GetAwaiter().GetResult() is not null;

try
{
    await scheduler.SubmitAsync(planParams, cancellationToken);
}
catch (Exception ex) when (ex.Message.Contains("not found") && ex.Message.Contains("Workflow definition"))
{
    logger.LogWarning("Alterations plan workflow missing; run feature registration/publish step first.");
}

When it happens

Trigger: Calling IAlterationPlanScheduler.SubmitAsync (e.g. via the alterations API endpoints) when FindWorkflowGraphAsync(ExecuteAlterationPlanWorkflow.WorkflowDefinitionId, VersionOptions.Published) returns null.

Common situations: Fresh database that never had the alterations workflow registered/published; the alterations feature/module not installed in the app; the workflow was unpublished or deleted; querying a store (tenant/database) different from where definitions were published.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• AlterationFaultCodes.PlanNotFound
• AlterationFaultCodes.PlanNotFound
• An alteration job with ID
• An alteration plan with ID
• AlterationFaultCodes.PlanNotFound

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

Appendix: source

Thrown at src/modules/Elsa.Alterations/Services/DefaultAlterationPlanScheduler.cs:45

    public DefaultAlterationPlanScheduler(IWorkflowDefinitionService workflowDefinitionService, IWorkflowDispatcher workflowDispatcher, IIdentityGenerator identityGenerator, IJsonSerializer jsonSerializer)
    {
        _workflowDefinitionService = workflowDefinitionService;
        _workflowDispatcher = workflowDispatcher;
        _identityGenerator = identityGenerator;
        _jsonSerializer = jsonSerializer;
    }

    /// <inheritdoc />
    public async Task<string> SubmitAsync(AlterationPlanParams planParams, CancellationToken cancellationToken = default)
    {
        if(string.IsNullOrWhiteSpace(planParams.Id))
            planParams.Id = _identityGenerator.GenerateId();
        
        var definitionId = ExecuteAlterationPlanWorkflow.WorkflowDefinitionId;
        var workflowGraph = await _workflowDefinitionService.FindWorkflowGraphAsync(definitionId, VersionOptions.Published, cancellationToken);
        
        if (workflowGraph == null)
            throw new($"Workflow definition with ID '{definitionId}' not found");
        
        var serializedPlan = _jsonSerializer.Serialize(planParams);
        var request = new DispatchWorkflowDefinitionRequest(workflowGraph.Workflow.Identity.Id)
        {
            Input = new Dictionary<string, object>
            {
                ["Plan"] = serializedPlan
            }
        };
        await _workflowDispatcher.DispatchAsync(request, cancellationToken);

        return planParams.Id;
    }
}

View on GitHub (pinned to fe9217bdfa)