Apex Queueable Patterns

Apex Queueable Patterns

Use this skill when designing or reviewing Apex jobs that use the Queueable interface for controlled async execution, multi-step chaining, outbound callouts, or error recovery through the Finalizer interface. The skill covers implementation patterns, stack depth management, state passing, and production-safe failure handling.

Before Starting

• Is the use case a single deferred operation, a multi-step chain, or a fan-out? Each has a different pattern.
• Does the job require callouts? If so, Database.AllowsCallouts must also be implemented.
• How deep can the chain realistically grow? The platform enforces a default maximum stack depth of 5 when using AsyncOptions.MaximumQueueableStackDepth.
• Does the job need to recover from failure or enqueue a follow-up regardless of success or failure? That is what the Finalizer interface is for.
• How is state passed between chained jobs? Serialized fields or record IDs are the safe options.

Core Concepts

The Queueable Interface

A Queueable class implements Queueable and defines a single execute(QueueableContext ctx) method. The job is enqueued with System.enqueueJob(new MyJob()) and runs asynchronously in a separate transaction with full governor limits — 100 SOQL queries, 150 DML statements, 12 MB heap, and 60 000 ms CPU time (per the Apex Developer Guide). The job ID returned by enqueueJob maps to an AsyncApexJob record that can be monitored.

Adding Database.AllowsCallouts to the implements clause is required for any Queueable that makes HTTP or web service callouts. Without it, a runtime exception is thrown even though the code compiles cleanly.

Chaining And Stack Depth

A Queueable can enqueue exactly one child job from within its execute() method. Attempting to enqueue a second child in the same execution throws a System.LimitException. This is the single-child chaining rule and it applies in production — in sandbox and scratch orgs the same rule holds, but tests run synchronously and skip the queue, so the limit is not exercised in unit tests.

Chaining can continue indefinitely by default, but uncontrolled infinite chains are a production risk. The AsyncOptions class lets you cap depth explicitly:

AsyncOptions opts = new AsyncOptions();
opts.MaximumQueueableStackDepth = 5;
System.enqueueJob(new MyJob(nextPayload), opts);

System.AsyncInfo.getCurrentQueueableStackDepth() returns the current depth so the job can stop or branch safely. Together these two APIs are the canonical pattern for bounded chaining in production code (Apex Developer Guide — Queueable Apex).

The Finalizer Interface

The Finalizer interface (System.Finalizer) runs after the parent Queueable completes — regardless of whether that Queueable succeeded or threw an uncaught exception. The Finalizer runs in its own separate Apex transaction with its own full governor limits. It is attached with System.attachFinalizer(new MyFinalizer()) inside the Queueable's execute() method, before any code that might fail.

The FinalizerContext passed to execute(FinalizerContext ctx) provides:

• ctx.getJobId() — the parent job's AsyncApexJob ID
• ctx.getResult() — ParentJobResult.SUCCESS or ParentJobResult.UNHANDLED_EXCEPTION
• ctx.getException() — the exception that terminated the parent, if any

A Finalizer can enqueue one additional Queueable. This is the safe mechanism for retry, dead-letter notification, or compensating transactions after Queueable failure. Only one Finalizer may be attached per Queueable (Apex Developer Guide — Transaction Finalizers).

State Passing Between Chained Jobs

Each Queueable runs in a separate transaction, so state must be serialized through job constructor fields. Collections of IDs, simple primitives, and serializable wrapper classes are all safe. Large SObject collections should be avoided in favor of passing a Set of IDs and re-querying in the next job. Do not rely on static variables to bridge jobs — static state does not survive across async transactions.

Mode Selection

This skill operates in three modes based on the practitioner's need:

• Mode 1 — Implement: Design a new Queueable or chain from scratch.
• Mode 2 — Review/Audit: Evaluate existing Queueable classes for anti-patterns, depth risk, missing callout declaration, or lack of Finalizer-based error handling.
• Mode 3 — Troubleshoot: Diagnose a failing, stuck, or looping Queueable job in production.

Common Patterns

Bounded Chained Processing With Stack Guard

When to use: A multi-step async workflow requires sequential jobs, each processing a slice of work, and the depth must be capped to prevent runaway chains.

How it works:

1. Each Queueable receives a payload (list of IDs to process, a cursor, or a batch number).
2. Before chaining, the job checks System.AsyncInfo.getCurrentQueueableStackDepth() against the configured max.
3. If depth is within limit, it enqueues the next job with AsyncOptions.MaximumQueueableStackDepth set.
4. If the depth cap is reached, the job logs the state and exits cleanly or triggers a Platform Event for external pickup.

Why not the alternative: Without the stack guard, an off-by-one error in termination logic or an unexpected data condition can produce an infinite chain that floods the async queue and degrades the org.

Finalizer-Based Error Recovery

When to use: The Queueable performs irreversible side effects (callouts, record updates) and the team needs guaranteed error notification or compensating action even when the job throws an uncaught exception.

How it works:

1. Call System.attachFinalizer(new MyFinalizer()) as the first line of execute() before any code that could throw.
2. In MyFinalizer.execute(FinalizerContext ctx), check ctx.getResult().
3. On ParentJobResult.UNHANDLED_EXCEPTION, log or create a failure record, send a Platform Event, or enqueue a compensating job.
4. On ParentJobResult.SUCCESS, optionally enqueue the next stage or record completion.

Why not the alternative: Without a Finalizer, an uncaught exception in a Queueable leaves no guaranteed cleanup path. try/catch alone cannot handle out-of-memory or system limit exceptions that terminate the transaction externally.

Callout Queueable With Retry

When to use: The job makes an outbound HTTP or web service call that can fail transiently, and the team wants automatic retry up to a bounded count.

How it works:

1. The class implements Queueable, Database.AllowsCallouts.
2. The constructor carries a retryCount integer and a payload.
3. The Finalizer checks for UNHANDLED_EXCEPTION. If retryCount < maxRetries, it enqueues the same job class with retryCount + 1.
4. After maxRetries, the Finalizer writes a failure record or fires an alert.

Why not the alternative: Re-enqueueing from inside catch inside execute() works only for caught exceptions. The Finalizer handles all failure modes including platform-level termination.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

• Class implements Queueable (and Database.AllowsCallouts if callouts are made).
• System.attachFinalizer() is called for any job where failure handling matters.
• execute() enqueues at most one child Queueable.
• Chained jobs use AsyncOptions.MaximumQueueableStackDepth to cap depth.
• Stack depth is checked with System.AsyncInfo.getCurrentQueueableStackDepth() before re-enqueueing.
• State is passed through serializable constructor fields, not static variables.
• Tests use Test.startTest() / Test.stopTest() boundaries.
• AsyncApexJob is used for operational visibility (job status, failure count).
• Callout errors and limit exceptions are handled in the Finalizer, not only in catch blocks.

Salesforce-Specific Gotchas

1. Single-child chaining rule is enforced at runtime, not compile time — code that enqueues two children inside execute() compiles cleanly but throws System.LimitException in the second enqueue call. Tests may not catch this because async jobs run synchronously in test context.
2. Finalizer runs in a separate transaction with fresh limits, but it is still subject to its own limits — a Finalizer that performs expensive SOQL or DML can itself hit governor limits and fail silently unless the Finalizer is also guarded.
3. AsyncOptions.MaximumQueueableStackDepth must be set on every enqueueJob call in the chain — setting it once on the first job does not propagate; each chained job must re-set the option or the guard does not apply downstream.

Output Artifacts

Related Skills

• apex/async-apex — use when the question is whether Queueable is the right async mechanism at all.
• apex/batch-apex-patterns — use when the volume or chunking need exceeds what Queueable chaining should handle.
• apex/exception-handling — use when the broader error handling and logging strategy is the focus.
• apex/governor-limits — use when the job is hitting CPU, heap, or DML limits inside execute().
• apex/debug-and-logging — use when diagnosing async job failures through log analysis and correlation IDs.