{"record":{"id":"3207f41b31014935","repo":"elsa-workflows/elsa-core","slug":"workflow-instance-not-found","errorCode":null,"errorMessage":"Workflow instance not found.","messagePattern":"Workflow instance not found\\.","errorType":"exception","errorClass":"WorkflowInstanceNotFoundException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs","lineNumber":200,"sourceCode":"        var workflowGraph = await GetWorkflowGraphAsync(workflowDefinitionHandle, cancellationToken);\n\n        var options = new WorkflowInstanceOptions\n        {\n            WorkflowInstanceId = WorkflowInstanceId,\n            CorrelationId = request.CorrelationId,\n            Name = request.Name,\n            ParentWorkflowInstanceId = request.ParentId,\n            Input = request.Input,\n            Properties = request.Properties\n        };\n\n        return workflowInstanceManager.CreateWorkflowInstance(workflowGraph.Workflow, options);\n    }\n\n    private async Task<WorkflowInstance> GetWorkflowInstanceAsync(CancellationToken cancellationToken)\n    {\n        var workflowInstance = await TryGetWorkflowInstanceAsync(cancellationToken);\n        if (workflowInstance == null) throw new WorkflowInstanceNotFoundException(\"Workflow instance not found.\", WorkflowInstanceId);\n        return workflowInstance;\n    }\n\n    private Task<WorkflowInstance?> TryGetWorkflowInstanceAsync(CancellationToken cancellationToken)\n    {\n        return workflowInstanceManager.FindByIdAsync(WorkflowInstanceId, cancellationToken);\n    }\n\n    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowInstance workflowInstance, CancellationToken cancellationToken)\n    {\n        var handle = WorkflowDefinitionHandle.ByDefinitionVersionId(workflowInstance.DefinitionVersionId);\n        return await GetWorkflowGraphAsync(handle, cancellationToken);\n    }\n\n    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowDefinitionHandle definitionHandle, CancellationToken cancellationToken)\n    {\n        var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(definitionHandle, cancellationToken);\n        if (!result.WorkflowDefinitionExists) throw new WorkflowDefinitionNotFoundException(\"Workflow definition not found.\", definitionHandle);","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs#L182-L218","documentation":"LocalWorkflowClient.GetWorkflowInstanceAsync loads the workflow instance by the client's WorkflowInstanceId via the instance manager. When no instance with that ID exists, it throws WorkflowInstanceNotFoundException with 'Workflow instance not found.'. Elsa throws this for local (in-process) client operations that require an existing instance.","triggerScenarios":"Any LocalWorkflowClient operation requiring the instance (e.g. CanExecuteBookmarkAsync, instance-scoped commands) where workflowInstanceManager.FindByIdAsync(WorkflowInstanceId) returns null because the ID does not exist or is not visible in the current tenant.","commonSituations":"Using an instance ID from a different database/environment; the instance was deleted (retention/cleanup) before the call; ID typo or copying the wrong field (e.g. correlation ID instead of instance ID); multi-tenant setup where the instance belongs to another tenant.","solutions":["Verify the workflow instance ID exists in the instance store (query by ID via the management API).","Use the TryGet-style/Find API first and handle a null result instead of the throwing path.","Check you are not confusing the instance ID with a correlation ID or workflow definition ID.","Confirm tenant/connection configuration matches where the instance was created."],"exampleFix":"// before\nvar client = workflowRuntime.CreateWorkflowClient(instanceId);\nawait client.ExecuteCommandAsync(...); // throws if instance missing\n\n// after\nvar instance = await workflowInstanceManager.FindByIdAsync(instanceId, ct);\nif (instance == null)\n{\n    logger.LogWarning(\"Workflow instance {InstanceId} not found; skipping.\", instanceId);\n    return;\n}\nvar client = workflowRuntime.CreateWorkflowClient(instanceId);\nawait client.ExecuteCommandAsync(...);","handlingStrategy":"validation","validationCode":"var instance = await workflowInstanceManager.FindByIdAsync(instanceId, ct);\nif (instance == null)\n{\n    logger.LogWarning(\"Workflow instance {InstanceId} not found.\", instanceId);\n    return;\n}","typeGuard":"bool WorkflowInstanceExists(WorkflowInstance? instance) => instance is not null;","tryCatchPattern":"try\n{\n    await client.ExecuteCommandAsync(cmd, ct);\n}\ncatch (WorkflowInstanceNotFoundException ex)\n{\n    logger.LogWarning(ex, \"Instance {InstanceId} does not exist.\", instanceId);\n}","preventionTips":["Confirm instance IDs come from the same store/tenant","Don't confuse instance IDs with correlation IDs","Check retention/cleanup hasn't removed the instance"],"tags":["workflow","runtime","not-found","instance"],"backgroundTag":"record-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"}