elsa-workflows/elsa-core · error · Exception

Could not find workflow definition with ID

Error message

Could not find workflow definition with ID {WorkflowDefinitionId}.

What it means

Thrown during WorkflowDefinitionActivity.InitializeAsync when the workflow definition referenced by WorkflowDefinitionId cannot be loaded from the definition store. The activity wraps another workflow definition, so a missing definition means the graph cannot be resolved at initialization time.

Solutions

Verify WorkflowDefinitionId matches an existing, published definition in the runtime's definition store (check the dashboard/API).
Publish the target workflow definition if it is still in draft.
Deploy/migrate the definitions to the current environment's database or fix the persistence connection configuration.
Check tenancy: ensure the definition exists in the tenant the workflow executes under.
Guard against deleted definitions by removing or updating referencing WorkflowDefinitionActivity instances when deleting a definition.

Example fix

// before
activity.WorkflowDefinitionId = "9a1f..."; // deleted definition

// after: resolve the ID from the management API at build time
var definition = await workflowDefinitionManager.FindByDefinitionIdAsync("my-flow", VersionOptions.Published);
activity.WorkflowDefinitionId = definition!.DefinitionId;

Defensive patterns

Strategy: try-catch

Validate before calling

var exists = (await workflowDefinitionManager.FindByDefinitionIdAsync(id, VersionOptions.Published)) != null;
if (!exists) throw new InvalidOperationException($"Referenced workflow definition '{id}' is not published in this environment/tenant.");

Try / catch

try
{
    await workflowDefinitionActivity.ExecuteAsync(context);
}
catch (Exception ex) when (ex.Message.StartsWith("Could not find workflow definition with ID"))
{
    logger.LogError(ex, "Referenced definition {Id} missing; ensure it is published and deployed", workflowDefinitionId);
    // compensate: notify ops or route to a fallback path
}

Prevention

Verify the referenced definition exists and is published in every target environment before deploying referring workflows.
Include definition deployment in your migration/release checklist.
Check tenant configuration when running multi-tenant.
Avoid hardcoding IDs from other environments; resolve published definitions by name at deploy time.

When it happens

Trigger: WorkflowDefinitionId points to a definition that was deleted, is a draft/unpublished version not visible to the runtime, lives in a different tenant, or the IWorkflowDefinitionProvider/store is misconfigured (e.g., wrong connection string, no definitions deployed).

Common situations: Definitions removed during cleanup while referring workflows remain, environment migrations where definitions were not deployed to the target database, multi-tenant setups where the definition exists only in another tenant, and referencing definitions by ID copied from a dev environment into production.

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

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

Appendix: source

Thrown at src/modules/Elsa.Workflows.Management/Activities/WorkflowDefinitionActivity/WorkflowDefinitionActivity.cs:58

    /// </summary>
    public string? LatestAvailablePublishedVersionId { get; set; }

    async ValueTask IInitializable.InitializeAsync(InitializationContext context)
    {
        // This is not just for efficiency but also a necessity to avoid potential race conditions.
        // Such conditions can occur when multiple threads are simultaneously creating consuming workflows,
        // especially when cached workflows are being updated during the graph construction process.
        if (IsInitialized)
            return;

        var serviceProvider = context.ServiceProvider;
        var cancellationToken = context.CancellationToken;

        // Find the workflow definition and not the graph; the graph must be computed at runtime, since NodeIds will vary across graphs.
        var workflowDefinition = await GetWorkflowDefinitionAsync(serviceProvider, cancellationToken);

        if (workflowDefinition == null)
            throw new Exception($"Could not find workflow definition with ID {WorkflowDefinitionId}.");

        var activityDescriptor = await FindActivityDescriptorAsync(serviceProvider);

        if (activityDescriptor == null)
        {
            var logger = serviceProvider.GetRequiredService<ILogger<WorkflowDefinitionActivity>>();
            logger.LogWarning("Could not find activity descriptor for activity type {ActivityType}", Type);
        }
        else
        {
            // Declare input and output variables.
            DeclareInputAsVariables(activityDescriptor, (_, variable) => Variables.Declare(variable));
            DeclareOutputAsVariables(activityDescriptor, (_, variable) => Variables.Declare(variable));
        }

        var workflowDefinitionService = serviceProvider.GetRequiredService<IWorkflowDefinitionService>();
        var workflowGraph = await workflowDefinitionService.MaterializeWorkflowAsync(workflowDefinition, cancellationToken);

View on GitHub (pinned to fe9217bdfa)