elsa-workflows/elsa-core · error · ArgumentException

A stimulus name is required.

Error message

A stimulus name is required.

What it means

NamedTriggerPayload's constructor requires a non-empty, non-whitespace stimulus name and throws ArgumentException naming the parameter otherwise. The name is the key under which the payload is registered for trigger matching. This is an argument-validation guard, so the exception is thrown at construction time, not at workflow execution time.

Solutions

  1. Pass a meaningful non-empty stimulus name when constructing the payload
  2. Validate/normalize the name before construction and fail with a clearer error
  3. Ensure the config or variable that supplies the name is populated

Example fix

// before
var payload = new NamedTriggerPayload(eventName, data);
// after
if (string.IsNullOrWhiteSpace(eventName)) throw new InvalidOperationException("Event name must be configured.");
var payload = new NamedTriggerPayload(eventName, data);
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(name)) throw new InvalidOperationException("Stimulus name is required.");

Try / catch

try { var p = new NamedTriggerPayload(name, payload); } catch (ArgumentException ex) when (ex.ParamName == "name") { /* surface config problem */ }

Prevention

When it happens

Trigger: new NamedTriggerPayload("", payload), new NamedTriggerPayload(" ", payload), or passing a name sourced from a null/empty variable or config value.

Common situations: Building payloads dynamically from event names that came back empty; reading the name from deserialized config where a field was missing; passing a variable that was never initialized.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/modules/Elsa.Workflows.Core/Models/NamedTriggerPayload.cs:21

/// <summary>
/// A trigger payload that carries its own stimulus name.
/// </summary>
/// <remarks>
/// Return instances of this type from <see cref="ITrigger.GetTriggerPayloadsAsync"/> when a single trigger needs to register payloads under
/// more than one stimulus name. The wrapper is unwrapped during indexing: the stored trigger's name and hash are derived from <see cref="Name"/>
/// and its payload from <see cref="Payload"/>. Payloads that are not wrapped are named using <see cref="TriggerIndexingContext.TriggerName"/>.
/// </remarks>
public record NamedTriggerPayload
{
    /// <summary>
    /// Initializes a new instance of the <see cref="NamedTriggerPayload"/> class.
    /// </summary>
    /// <param name="name">The stimulus name to register the payload under.</param>
    /// <param name="payload">The payload to register.</param>
    public NamedTriggerPayload(string name, object payload)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("A stimulus name is required.", nameof(name));

        if (payload is NamedTriggerPayload)
            throw new ArgumentException("A NamedTriggerPayload cannot wrap another NamedTriggerPayload.", nameof(payload));

        Name = name;
        Payload = payload;
    }

    /// <summary>
    /// The stimulus name to register the payload under. Publishers of this stimulus compute their hash from this same name.
    /// </summary>
    public string Name { get; }

    /// <summary>
    /// The payload to register. This is what gets stored; the wrapper itself never is, since the constructor refuses to wrap another
    /// <see cref="NamedTriggerPayload"/>.
    /// </summary>
    public object Payload { get; }

View on GitHub (pinned to fe9217bdfa)