Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

The AggregateException class

Reference for AggregateException in C#: how Task.Wait, Parallel and Task.WhenAll combine failures, and how to use InnerExceptions, Flatten and Handle.

System.AggregateException bundles several exceptions into one. It appears whenever more than one thing can fail at once: Parallel.For and Parallel.ForEach, PLINQ queries, and blocking on tasks with Task.Wait(), Task.Result or Task.WaitAll(). The individual failures are available through its InnerExceptions collection.

When you await a task instead of blocking, the runtime unwraps the aggregate and throws only the first inner exception. That is convenient, but it also means you lose the others. To see them all, keep the task and read task.Exception.

C#
try
{
    Task.WaitAll(taskA, taskB);
}
catch (AggregateException ae)
{
    foreach (Exception e in ae.InnerExceptions) { /* inspect */ }
}

Try it

C# Collecting failures from several tasks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# await shows one, Exception shows all

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public class AggregateException : Exception
{
    public AggregateException();
    public AggregateException(string? message);
    public AggregateException(IEnumerable<Exception> innerExceptions);
    public AggregateException(params Exception[] innerExceptions);
    public AggregateException(string? message, IEnumerable<Exception> innerExceptions);

    public ReadOnlyCollection<Exception> InnerExceptions { get; }
    public AggregateException Flatten();
    public void Handle(Func<Exception, bool> predicate);
    public override Exception GetBaseException();
}
Member Description
InnerExceptions All collected exceptions, in the order they were added.
InnerException Only the first of them (inherited from Exception).
Flatten() Returns a new aggregate with nested aggregates expanded into one level.
Handle(predicate) Calls the predicate for each inner exception. If it returns false for any, throws a new AggregateException containing just those.
GetBaseException() Returns the innermost exception that is not an aggregate.

Errors: ArgumentNullException if an inner exception is null or the collection is null.

Usage notes

  • Order is not guaranteed for tasks that run in parallel. Sort or group the exceptions if the output must be stable.
  • await unwraps; Wait() and Result wrap. Blocking calls always hand you an AggregateException, even for a single failure. This is one reason to prefer await.
  • await Task.WhenAll(...) throws only the first exception. Inspect whenAllTask.Exception after catching to see every failure.
  • Parallel loops stop early. After one iteration throws, Parallel.ForEach stops starting new iterations, so you may collect fewer exceptions than there were bad items.
  • Flatten before you enumerate when tasks can themselves contain tasks, so a nested aggregate does not hide the real exception.
  • Handle is for filtering. Return true for exceptions you have dealt with; anything else is rethrown in a new aggregate.
  • Unobserved task exceptions (a faulted task nobody awaited) are no longer fatal; they surface through TaskScheduler.UnobservedTaskException after garbage collection.
  • Do not create aggregates by hand unless you collect errors yourself, for example while processing a batch and reporting all failures at the end.