What causes "handler" in Cysharp/UniTask?

Null-check the handler before calling Add

Cysharp/UniTask · error · ArgumentNullException

handler

Error message

handler

What it means

Thrown by TriggerEvent<T>.Add when the handler argument is null. UniTask requires a valid ITriggerHandler<T> because the trigger maintains a doubly-linked list of handlers with Prev/Next pointers; a null node would cause NullReferenceException during iteration. This is a fail-fast guard at the API boundary.

Source

Thrown at src/UniTask/Assets/Plugins/UniTask/Runtime/TriggerEvent.cs:173

                }

                var next = h == iteratingNode ? h.Next : iteratingNode;
                iteratingNode = null;
                Remove(h);
                h = next;
            }

            iteratingNode = null;
            if (iteratingHead != null)
            {
                Add(iteratingHead);
                iteratingHead = null;
            }
        }

        public void Add(ITriggerHandler<T> handler)
        {
            if (handler == null) throw new ArgumentNullException(nameof(handler));

            // zero node.
            if (head == null)
            {
                head = handler;
                return;
            }

            if (iteratingNode != null)
            {
                if (iteratingHead == null)
                {
                    iteratingHead = handler;
                    return;
                }

                var last = iteratingHead.Prev;
                if (last == null)

View on GitHub (pinned to ceac8d6946)

Solutions

Null-check the handler before calling Add
Ensure the factory or builder that produces the handler never returns null
Use a guard clause: if (handler != null) triggerEvent.Add(handler);

Example fix

// before
triggerEvent.Add(maybeNullHandler);

// after
if (maybeNullHandler != null)
{
    triggerEvent.Add(maybeNullHandler);
}

Defensive patterns

Strategy: validation

Validate before calling

if (handler != null)
{
    triggerEvent.Add(handler);
}

Type guard

static bool IsValidHandler<T>(ITriggerHandler<T> handler) => handler != null;

Prevention

Always null-check handlers before calling Add
Ensure handler factory methods never return null
Use a helper extension method that does the null check internally

When it happens

Trigger: Calling triggerEvent.Add(null) directly, or passing a handler variable that was never assigned or was conditionally set to null before the Add call.

Common situations: Registering a handler from a factory method that can return null, or after a conditional check that skipped handler creation. Subscribing in a loop where some iterations have no handler to add.

Related errors

AI-assisted analysis of Cysharp/UniTask@ceac8d6946 (2026-08-13). Data as JSON: /api/errors/e2e6de79b6d43b57. Report an issue: GitHub.