elsa-workflows/elsa-core · error · WorkflowMaterializerNotFoundException

Materializer not found. The materializer may be disabled or…

Error message

Materializer not found. The materializer may be disabled or not registered

What it means

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.

Solutions

1. Register the required materializer/feature in the host (e.g. add the workflow definitions/JSON feature module so its materializer is in DI).
2. Check the definition's MaterializerName against registered materializers and fix the stored name if it is stale or misspelled.
3. Verify all Elsa packages used when the definition was created are also referenced in this application.
4. Catch WorkflowMaterializerNotFoundException and report the missing materializer name to guide remediation.

Example fix

// before
services.AddElsa(elsa => elsa.AddWorkflows()); // materializer feature missing

// after
services.AddElsa(elsa => elsa
    .AddWorkflows()
    .UseWorkflowManagement(management => management.UseJsonDefinitions()) // registers the JSON materializer
);

var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(handle, ct);
if (result.WorkflowDefinitionExists && !result.WorkflowGraphExists)
    throw new InvalidOperationException($"Materializer '{result.WorkflowDefinition!.MaterializerName}' is not registered in this host.");

try
{
    await client.ResumeAsync(ct);
}
catch (WorkflowMaterializerNotFoundException ex)
{
    logger.LogError(ex, "Materializer {Name} missing; register the required feature/package.", ex.MaterializerName);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• The specified activity is not part of the workflow.
• Workflow definition not found.
• Workflow instance not found.
• Workflow definition not found.
• AlterationFaultCodes.PlanNotFound

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

Appendix: source

Thrown at src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs:219

        return workflowInstance;
    }

    private Task<WorkflowInstance?> TryGetWorkflowInstanceAsync(CancellationToken cancellationToken)
    {
        return workflowInstanceManager.FindByIdAsync(WorkflowInstanceId, cancellationToken);
    }

    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowInstance workflowInstance, CancellationToken cancellationToken)
    {
        var handle = WorkflowDefinitionHandle.ByDefinitionVersionId(workflowInstance.DefinitionVersionId);
        return await GetWorkflowGraphAsync(handle, cancellationToken);
    }

    private async Task<WorkflowGraph> GetWorkflowGraphAsync(WorkflowDefinitionHandle definitionHandle, CancellationToken cancellationToken)
    {
        var result = await workflowDefinitionService.TryFindWorkflowGraphAsync(definitionHandle, cancellationToken);
        if (!result.WorkflowDefinitionExists) throw new WorkflowDefinitionNotFoundException("Workflow definition not found.", definitionHandle);
        if (!result.WorkflowGraphExists) throw new WorkflowMaterializerNotFoundException(result.WorkflowDefinition!.MaterializerName);
        return result.WorkflowGraph!;
    }
}

View on GitHub (pinned to fe9217bdfa)