{"record":{"id":"699b6db2741a1b03","repo":"elsa-workflows/elsa-core","slug":"workflow-definition-not-found-backgroundactivityinvoker","errorCode":null,"errorMessage":"Workflow definition not found","messagePattern":"Workflow definition not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/BackgroundActivityInvoker.cs","lineNumber":34,"sourceCode":"    IVariablePersistenceManager variablePersistenceManager,\n    IActivityInvoker activityInvoker,\n    IActivityPropertyLogPersistenceEvaluator activityPropertyLogPersistenceEvaluator,\n    WorkflowHeartbeatGeneratorFactory workflowHeartbeatGeneratorFactory,\n    IServiceProvider serviceProvider,\n    ILogger<BackgroundActivityInvoker> logger)\n    : IBackgroundActivityInvoker\n{\n    private readonly ILogger _logger = logger;\n\n    /// <inheritdoc />\n    public async Task ExecuteAsync(ScheduledBackgroundActivity scheduledBackgroundActivity, CancellationToken cancellationToken = default)\n    {\n        var workflowInstanceId = scheduledBackgroundActivity.WorkflowInstanceId;\n        var workflowInstance = await workflowInstanceManager.FindByIdAsync(workflowInstanceId, cancellationToken);\n        if (workflowInstance == null) throw new(\"Workflow instance not found\");\n        var workflowState = workflowInstance.WorkflowState;\n        var workflow = await workflowDefinitionService.FindWorkflowGraphAsync(workflowInstance.DefinitionVersionId, cancellationToken);\n        if (workflow == null) throw new(\"Workflow definition not found\");\n        var workflowExecutionContext = await WorkflowExecutionContext.CreateAsync(serviceProvider, workflow, workflowState, cancellationToken: cancellationToken);\n        var activityNodeId = scheduledBackgroundActivity.ActivityNodeId;\n        var activityExecutionContext = workflowExecutionContext.ActivityExecutionContexts.First(x => x.NodeId == activityNodeId);\n\n        using (workflowHeartbeatGeneratorFactory.CreateHeartbeatGenerator(workflowExecutionContext))\n        {\n            await variablePersistenceManager.LoadVariablesAsync(workflowExecutionContext);\n            activityExecutionContext.SetIsBackgroundExecution();\n            await activityInvoker.InvokeAsync(activityExecutionContext);\n            await variablePersistenceManager.SaveVariablesAsync(workflowExecutionContext);\n        }\n        await ResumeWorkflowAsync(activityExecutionContext, scheduledBackgroundActivity);\n    }\n\n    private async Task ResumeWorkflowAsync(ActivityExecutionContext activityExecutionContext, ScheduledBackgroundActivity scheduledBackgroundActivity)\n    {\n        var cancellationToken = activityExecutionContext.CancellationToken;\n        var activityNodeId = scheduledBackgroundActivity.ActivityNodeId;","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/BackgroundActivityInvoker.cs#L16-L52","documentation":"Thrown by BackgroundActivityInvoker.ExecuteAsync when the workflow instance was found but its definition graph cannot be resolved: workflowDefinitionService.FindWorkflowGraphAsync(workflowInstance.DefinitionVersionId) returned null. The instance's DefinitionVersionId no longer resolves to a workflow graph, so the background activity cannot be resumed.","triggerScenarios":"The workflow definition (or the specific version) referenced by the stored instance's DefinitionVersionId was deleted; the definition service/provider backing the lookup is not registered or points at a different store; the definition ID stored on the instance is from another environment.","commonSituations":"Deleting or re-importing workflow definitions while instances are still running; database/tenant mismatch between the instance store and the definition store; missing workflow definition provider registration in the host; staging data copied partially (instances without their definitions).","solutions":["Verify the definition referenced by workflowInstance.DefinitionVersionId exists in the same store/tenant the runtime reads from; restore or re-import it if deleted.","Check host configuration: all required workflow definition providers/features (e.g. management feature, definition store) are registered so FindWorkflowGraphAsync can resolve the ID.","Confirm the worker uses the same database/connection and tenant as the environment that created the instance.","If the definition is unrecoverable, terminate/cancel the stale instances and drop their queued background activities instead of resuming them."],"exampleFix":"// before: assuming definitions are always present\nvar workflow = await workflowDefinitionService.FindWorkflowGraphAsync(instance.DefinitionVersionId, ct);\n\n// after: keep definitions and instances together; guard before scheduling background work\nvar graph = await workflowDefinitionService.FindWorkflowGraphAsync(instance.DefinitionVersionId, ct);\nif (graph == null)\n    throw new InvalidOperationException($\"Definition {instance.DefinitionVersionId} missing for instance {instance.Id}; restore the definition before resuming.\");","handlingStrategy":"try-catch","validationCode":"var graph = await workflowDefinitionService.FindWorkflowGraphAsync(workflowInstance.DefinitionVersionId, ct);\nif (graph is null)\n{\n    logger.LogWarning(\"Definition {DefinitionVersionId} for instance {InstanceId} is missing; cannot resume background activity.\",\n        workflowInstance.DefinitionVersionId, workflowInstance.Id);\n    return;\n}","typeGuard":"if (workflow is null) throw new InvalidOperationException($\"Definition {workflowInstance.DefinitionVersionId} not resolvable for instance {workflowInstance.Id}.\");","tryCatchPattern":"try\n{\n    await backgroundActivityInvoker.ExecuteAsync(scheduledBackgroundActivity, ct);\n}\ncatch (Exception ex) when (ex.Message == \"Workflow definition not found\")\n{\n    logger.LogWarning(ex, \"Cannot resume background activity {ActivityId}: definition {DefinitionVersionId} is unavailable.\",\n        scheduledBackgroundActivity.Id, definitionVersionId);\n}","preventionTips":["Never delete workflow definitions or versions while instances referencing them are still running; cancel instances first.","Deploy definitions together with the instance data when copying between environments.","Register all workflow definition providers/features in every host that runs background activity invokers.","Verify tenant/definition store configuration matches between instance creation and background execution."],"tags":["workflow","dotnet","background-activity","definition-versioning","elsa"],"backgroundTag":"entity-not-found","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}