{"record":{"id":"44cdd603e21e0308","repo":"elsa-workflows/elsa-core","slug":"materializer-not-found-the-materializer-may-be-disabled-or","errorCode":null,"errorMessage":"Materializer not found. The materializer may be disabled or not registered","messagePattern":"Materializer not found\\. The materializer may be disabled or not registered","errorType":"exception","errorClass":"WorkflowMaterializerNotFoundException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs","lineNumber":219,"sourceCode":"        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);\n        if (!result.WorkflowGraphExists) throw new WorkflowMaterializerNotFoundException(result.WorkflowDefinition!.MaterializerName);\n        return result.WorkflowGraph!;\n    }\n}","sourceCodeStart":201,"sourceCodeEnd":222,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs#L201-L222","documentation":"LocalWorkflowClient.GetWorkflowGraphAsync throws WorkflowMaterializerNotFoundException when the definition exists but no workflow graph could be produced (WorkflowGraphExists == false). The message identifies the materializer name recorded on the definition, which is either disabled, not registered in DI, or fails to produce a graph.","triggerScenarios":"Loading a definition whose MaterializerName does not match any registered IMaterializer — e.g. a definition created by a feature/package (JSON, YAML, custom DSL) whose materializer is not registered in the host, or an unknown materializer name in stored definition data.","commonSituations":"Missing package registration (e.g. Elsa JSON/workflow-definition feature not added to the host); version upgrade renaming a materializer; definition data written by another environment with an extra materializer enabled; typo in custom materializer name.","solutions":["Register the required materializer/feature in the host (e.g. add the workflow definitions/JSON feature module so its materializer is in DI).","Check the definition's MaterializerName against registered materializers and fix the stored name if it is stale or misspelled.","Verify all Elsa packages used when the definition was created are also referenced in this application.","Catch WorkflowMaterializerNotFoundException and report the missing materializer name to guide remediation."],"exampleFix":"// before\nservices.AddElsa(elsa => elsa.AddWorkflows()); // materializer feature missing\n\n// after\nservices.AddElsa(elsa => elsa\n    .AddWorkflows()\n    .UseWorkflowManagement(management => management.UseJsonDefinitions()) // registers the JSON materializer\n);","handlingStrategy":"validation","validationCode":"var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(handle, ct);\nif (result.WorkflowDefinitionExists && !result.WorkflowGraphExists)\n    throw new InvalidOperationException($\"Materializer '{result.WorkflowDefinition!.MaterializerName}' is not registered in this host.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    await client.ResumeAsync(ct);\n}\ncatch (WorkflowMaterializerNotFoundException ex)\n{\n    logger.LogError(ex, \"Materializer {Name} missing; register the required feature/package.\", ex.MaterializerName);\n}","preventionTips":["Register every materializer feature the stored definitions use","Keep Elsa packages consistent between authoring and runtime hosts","After upgrades, verify stored MaterializerName values still resolve"],"tags":["workflow","materializer","runtime","missing-registration"],"backgroundTag":"missing-dependency","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"}