Acta. Durable execution for .NET

learn actasplit work across child jobs

How to handle child jobs that fail

A group of children never throws by itself. A failed child shows in the Failed list of the wait or the map, and ThrowIfAnyFailed is how the parent chooses to fail with it.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/200-durable-execution/219-child-failure-outcomes
Read as

1Carry on without the items that failed

The map does not throw for a failed item. Failed lists them, and this parent returns a partial result and lands Succeeded.

child-failure-outcomes.csexcerpt
string[] ids = ["item-a", "item-b", "item-c"];

var result = await context.MapAsync(
    "process",
    ids,
    itemKey: id => id,
    child: id => new ProcessItem(id, ShouldFail: id == "item-b"),
    ct
);
 
var succeeded = result.Items.Count(i => i.Outcome.Succeeded);
 
foreach (var f in result.Failed)
{
    Console.WriteLine($"  item {f.Key} failed (status={f.Outcome.Status}); continuing without it");
}

return new MapReport($"{succeeded}/{ids.Length} items succeeded");

2Or fail the parent with its failed child

ThrowIfAnyFailed throws ChildGroupException; the parent lands Failed.

child-failure-outcomes.csexcerpt
// Scenario 2: two children enqueued and waited for; one child fails. The handler calls
// ThrowIfAnyFailed on the outcome, and the parent lands Failed at once, with no retry.
[Job("run-join-escalated")]
public async Task HandleJoinEscalated(RunJoinEscalated _, JobContext context, CancellationToken ct)
{
    var alpha = await context.EnqueueChildAsync("alpha", new RunChild("alpha", ShouldFail: false), ct);
    var beta = await context.EnqueueChildAsync("beta", new RunChild("beta", ShouldFail: true), ct);

    var result = await context.WaitChildrenAsync([alpha, beta], ct);

    foreach (var child in result.Failed)
    {
        Console.WriteLine($"  child {child.JobRef} failed (status={child.Status})");
    }

    result.ThrowIfAnyFailed();
}

3Run it and check the output

From a clone of the Acta repository, with the .NET 10 SDK:

Terminal
dotnet run --project learn/200-durable-execution/219-child-failure-outcomes
Its output must contain
item item-b failed (status=Failed); continuing without it
parent: Succeeded, report: 2/3 items succeeded
parent: Failed (expected Failed)

Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.

Remember

  • A child alerts on its own failure even when the parent handles it. When the parent reports the failure, declare the child AlertProfile = AlertProfileCode.None.
  • A failed child carries the message it failed with in FailureMessage.
  • ThrowIfAnyFailed() fails the parent at once, with no retry: a retry would find the same failed child. To recover, restart the child, then the parent.

The whole program

Every file of learn/200-durable-execution/219-child-failure-outcomes, as it is compiled.

UseLocalDatabase is a helper of the Acta repository, not of the packages. In your own app, register the database with UseSqlite, UsePostgres or UseSqlServer, as in how to run your first job.

child-failure-outcomes.cs133 lines
child-failure-outcomes.cs
// How to handle child jobs that fail
// A group of children never throws by itself. A failed child shows in the `Failed` list of the wait or the map, and
// `ThrowIfAnyFailed` is how the parent chooses to fail with it.
using Acta;
using Acta.Learn.ChildFailureOutcomes;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ChildFailureOutcomesJobs>("child-failure-outcomes");
});

using var host = builder.Build();
await host.StartAsync();

var jobs = host.Services.GetRequiredService<IJobs>();

// --- Scenario 1: MapAsync, soft handling ---
// The handler inspects MapOutcome.Failed and returns a partial result; the parent lands Succeeded.
Console.WriteLine("--- scenario 1: map with one failing item, soft handling ---");
var mapOutcome = await jobs.CallAsync(ChildFailureOutcomesJobs.RunMapSoft());
Console.WriteLine($"parent: {mapOutcome.Status}, report: {mapOutcome.Value!.Summary}");

// --- Scenario 2: WaitChildrenAsync, ThrowIfAnyFailed escalation ---
// The handler calls ThrowIfAnyFailed after a child fails; ChildGroupException fails the parent at once,
// since a retry would find the same failed child. The driver reads the Failed status without the
// exception propagating here.
Console.WriteLine("--- scenario 2: children with one failing, ThrowIfAnyFailed ---");
var joinOutcome = await jobs.CallAsync<RunJoinEscalated>(new RunJoinEscalated());
Console.WriteLine($"parent: {joinOutcome.Status} (expected Failed)");

await host.StopAsync();

namespace Acta.Learn.ChildFailureOutcomes
{
    // ---- scenario 1 inputs and results ----

    public readonly record struct RunMapSoft;

    public sealed record ProcessItem(string Id, bool ShouldFail);

    public sealed record MapReport(string Summary);

    // ---- scenario 2 inputs ----

    public readonly record struct RunJoinEscalated;

    public sealed record RunChild(string Name, bool ShouldFail);

    public sealed class FailureScenarioJobs
    {
        // Scenario 1: map over three items; one item is rigged to fail. After waiting, the handler
        // checks MapOutcome.Failed and returns a partial summary; the parent lands Succeeded.
        [Job("run-map-soft")]
        public async Task<MapReport> HandleMapSoft(RunMapSoft _, JobContext context, CancellationToken ct)
        {
            string[] ids = ["item-a", "item-b", "item-c"];

            // learn: 1. Carry on without the items that failed
            // The map does not throw for a failed item. `Failed` lists them, and this parent returns a partial result
            // and lands Succeeded.
            var result = await context.MapAsync(
                "process",
                ids,
                itemKey: id => id,
                child: id => new ProcessItem(id, ShouldFail: id == "item-b"),
                ct
            );
 
            var succeeded = result.Items.Count(i => i.Outcome.Succeeded);
 
            foreach (var f in result.Failed)
            {
                Console.WriteLine($"  item {f.Key} failed (status={f.Outcome.Status}); continuing without it");
            }
            // learn: end

            return new MapReport($"{succeeded}/{ids.Length} items succeeded");
        }

        // FailAsync ends the job Failed at once, with no retry, and leaves MaxAttempts to absorb crashes; a thrown
        // exception would retry, and MaxAttempts = 1 would fail the job on its first crash too.
        [Job("process-item")]
        public async Task ProcessItemHandler(ProcessItem input, JobContext context, CancellationToken ct)
        {
            await Task.Delay(100, ct);
            if (input.ShouldFail)
            {
                Console.WriteLine($"  item {input.Id}: failing");
                await context.FailAsync($"item {input.Id} failed intentionally", ct);
            }
            Console.WriteLine($"  item {input.Id}: done");
        }

        // Scenario 2: two children enqueued and waited for; one child fails. The handler calls
        // ThrowIfAnyFailed on the outcome, and the parent lands Failed at once, with no retry.
        [Job("run-join-escalated")]
        public async Task HandleJoinEscalated(RunJoinEscalated _, JobContext context, CancellationToken ct)
        {
            var alpha = await context.EnqueueChildAsync("alpha", new RunChild("alpha", ShouldFail: false), ct);
            var beta = await context.EnqueueChildAsync("beta", new RunChild("beta", ShouldFail: true), ct);

            var result = await context.WaitChildrenAsync([alpha, beta], ct);

            foreach (var child in result.Failed)
            {
                Console.WriteLine($"  child {child.JobRef} failed (status={child.Status})");
            }

            // learn: 2. Or fail the parent with its failed child
            // ThrowIfAnyFailed throws ChildGroupException; the parent lands Failed.
            result.ThrowIfAnyFailed();
            // learn: end
        }

        // FailAsync, as in process-item: the failing child ends at once and keeps its budget for crashes.
        [Job("run-child")]
        public async Task RunChildHandler(RunChild input, JobContext context, CancellationToken ct)
        {
            await Task.Delay(100, ct);
            if (input.ShouldFail)
            {
                Console.WriteLine($"  child {input.Name}: failing");
                await context.FailAsync($"child {input.Name} failed intentionally", ct);
            }
            Console.WriteLine($"  child {input.Name}: done");
        }
    }
}

Where to go next

New to Acta?

Acta is durable execution for .NET: workflows and jobs that survive restarts, as a library inside your application with its durable state in your SQL database.