elsa-workflows/elsa-core · warning · FaultException

FaultException raised by Fault activity

Error message

FaultException raised by Fault activity

What it means

The Fault activity's Execute reads its Code, Category, Type, and Message inputs and throws a FaultException with those values. This is the intended mechanism for deliberately faulting a workflow: the thrown exception is converted into a workflow fault (incident) rather than a bug. The message 'FaultException raised by Fault activity' is the default message when the Message input is not set.

Solutions

1. Set the Fault activity's Message (and Code/Category/Type) inputs to a descriptive value for triage.
2. If the fault is unintended, inspect the workflow path/conditions that routed execution into the Fault activity and fix the branching.
3. Handle expected faults downstream via workflow fault/incident handling (compensation, retry, or catch semantics) instead of letting the instance end in fault.

Example fix

// before
new Fault { Code = new("ERR-409") } // no message
// after
new Fault { Code = new("ERR-409"), Category = new("Business"), Message = new("Order total exceeds credit limit") }

// Pre-check the business rule before the Fault activity can be reached
if (order.Total > creditLimit)
    throw new InvalidOperationException($"Order {order.Id} exceeds credit limit {creditLimit}");

try { await runner.RunAsync(workflow); }
catch (FaultException ex) when (ex.Category == "Business") { /* route to review queue */ }

When it happens

Trigger: A workflow contains a Fault activity and execution reaches it — either as designed (validation failure, business rule violation) or accidentally due to a miswired condition. When the Message input is left unset, the default message 'FaultException raised by Fault activity' is used.

Common situations: Business-rule checks implemented with Fault (e.g. 'order total exceeds limit'); workflows faulting unexpectedly because an If/condition routed into a Fault activity; missing Message input making incidents harder to triage.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• AlterationFaultCodes.PlanNotFound
• {fault.Code}
• Activity type not found
• No alterations found in the transient properties.
• No alteration log found in the transient properties.

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

Appendix: source

Thrown at src/modules/Elsa.Workflows.Core/Activities/Fault.cs:71

        DisplayName = "Type",
        Description = "The type of fault. Examples: System, Business, Integration, etc."
        )]
    public Input<string> FaultType { get; set; } = null!;

    /// <summary>
    /// The message to include with the fault.
    /// </summary>
    [Input(Description = "The message to include with the fault.")]
    public Input<string?> Message { get; set; } = null!;

    /// <inheritdoc />
    protected override void Execute(ActivityExecutionContext context)
    {
        var code = Code.GetOrDefault(context) ?? "0";
        var category = Category.GetOrDefault(context) ?? "General";
        var type = FaultType.GetOrDefault(context) ?? "System";
        var message = Message.GetOrDefault(context);
        throw new FaultException(code, category, type, message);
    }
}

View on GitHub (pinned to fe9217bdfa)