elsa-workflows/elsa-core · error · ArgumentOutOfRangeException

Priority must be between 0 and 100.

Error message

Priority must be between 0 and 100.

What it means

Normalize() validates that the UserTaskDefinition's Priority is within the inclusive range 0..100 and throws ArgumentOutOfRangeException when it is outside. Priority drives ordering of tasks in queues/UX, so out-of-range values are rejected at materialization time.

Solutions

  1. Clamp the priority before normalizing: Math.Clamp(priority, 0, 100).
  2. Fix the source value/scale — map the external scale into 0–100.
  3. If you need a 'no priority' state, use null rather than a sentinel like -1 if the property is nullable.

Example fix

// before
definition.Priority = externalPriority; // external scale 1-10
// after
definition.Priority = Math.Clamp(externalPriority * 10, 0, 100);
Defensive patterns

Strategy: validation

Validate before calling

if (definition.Priority is < 0 or > 100)
    definition.Priority = Math.Clamp(definition.Priority, 0, 100);

Try / catch

try { definition = definition.Normalize(); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == nameof(UserTaskDefinition.Priority)) { /* clamp and retry */ }

Prevention

When it happens

Trigger: Constructing or deserializing a UserTaskDefinition with Priority set to e.g. 150, -1, int.MaxValue, or a default of 0 intentionally misread; calling Normalize() (directly or through DefaultUserTaskManager.ProjectAsync) then throws.

Common situations: UI sliders that allow values beyond 100; configurations importing priority from another system on a 1–10 scale misinterpreted as 0–100; uninitialized fields set to -1 as a sentinel.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/modules/Elsa.UserTasks/Models/UserTaskModels.cs:215

    public bool EnableTimeoutOutcome { get; init; }
    public bool EnableCancellationOutcome { get; init; }

    public UserTaskDefinitionSnapshot Normalize()
    {
        var actions = Actions.Count == 0
            ? [new UserTaskAction("Complete", "Complete")]
            : Actions;

        if (string.IsNullOrWhiteSpace(Title))
            throw new ArgumentException("A User Task title is required.", nameof(Title));
        if (actions.Any(x => string.IsNullOrWhiteSpace(x.Key) || string.IsNullOrWhiteSpace(x.Label)))
            throw new ArgumentException("User Task action keys and labels are required.", nameof(Actions));
        if (actions.Any(x => string.Equals(x.Key, "Timeout", StringComparison.OrdinalIgnoreCase) || string.Equals(x.Key, "Cancelled", StringComparison.OrdinalIgnoreCase)))
            throw new ArgumentException("Timeout and Cancelled are reserved User Task action keys.");
        if (actions.Select(x => x.Key).Distinct(StringComparer.OrdinalIgnoreCase).Count() != actions.Count)
            throw new ArgumentException("User Task action keys must be unique.");
        if (Priority is < 0 or > 100)
            throw new ArgumentOutOfRangeException(nameof(Priority), "Priority must be between 0 and 100.");
        if (Invitations.Any(x => string.IsNullOrWhiteSpace(x.VerifierName) || x.AllowedActions.Count == 0 || x.AllowedActions.Any(string.IsNullOrWhiteSpace)))
            throw new ArgumentException("Invitation verifier names and allowed actions are required.", nameof(Invitations));
        if (Invitations.Any(invitation => invitation.AllowedActions.Any(allowed => !actions.Any(action => string.Equals(action.Key, allowed, StringComparison.OrdinalIgnoreCase)))))
            throw new ArgumentException("Invitation actions must be configured User Task actions.", nameof(Invitations));

        return this with { Actions = actions };
    }
}

public sealed class UserTask
{
    public string Id { get; set; } = Guid.NewGuid().ToString("N");
    public string TenantId { get; set; } = "";
    public string WorkflowDefinitionId { get; set; } = "";
    public string? WorkflowDefinitionName { get; set; }
    public int? WorkflowDefinitionVersion { get; set; }
    public string WorkflowInstanceId { get; set; } = "";
    /// <summary>A safe, host-authored instance reference (correlation ID or instance name). Never a bookmark or token.</summary>

View on GitHub (pinned to fe9217bdfa)