Apex Transaction Finalizers

Apex Transaction Finalizers

This skill activates when a Queueable job needs guaranteed post-execution behavior — cleanup, retry, or failure logging — that must run even if the parent Queueable throws an unhandled exception. Use System.attachFinalizer() to bind a System.Finalizer implementation to a Queueable; the Finalizer runs in a separate Apex transaction with full governor limits after the parent job finishes.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the parent job is a Queueable (not Batch, Scheduled, or @future). Transaction Finalizers are only supported on Queueable jobs.
• Identify the failure scenario: Is this a retry (re-enqueue the same job), a compensation (write a failure record / publish a PE), or silent logging?
• Determine a retry ceiling. Finalizers can enqueue exactly one new Queueable — if that Queueable also has a Finalizer, the chain continues. Without a retry limit you risk infinite loops.
• Check the API version of the Queueable class — System.attachFinalizer() requires API v53.0+ (Summer '21).
• The Finalizer does not run if the parent job was aborted via System.abortJob(). Plan for that case separately.

Core Concepts

Finalizer Lifecycle

When System.attachFinalizer(myFinalizer) is called inside a Queueable's execute() method, the platform registers the Finalizer to execute after the parent job's transaction closes — whether it committed successfully or was rolled back due to an unhandled exception. The Finalizer runs in a completely separate Apex transaction with fresh governor-limit counters (100 SOQL queries, 150 DML statements, etc.). The parent transaction's state (variable values, uncommitted DML) is not visible to the Finalizer.

FinalizerContext API

The Finalizer's execute(FinalizerContext ctx) method receives a FinalizerContext object with three key members:

Always gate retry / compensation logic on ctx.getResult() to avoid double-processing on success.

Enqueue Constraint

A Finalizer may enqueue exactly one new Queueable job via System.enqueueJob(). Attempting to enqueue more than one throws a System.AsyncException. A Finalizer cannot attach another Finalizer to itself — System.attachFinalizer() called from within a Finalizer context throws a System.AsyncException.

Abort Gap

If the parent Queueable is terminated via System.abortJob(), the Finalizer is not invoked. This is a hard platform constraint with no workaround at the Finalizer layer. If abort-path cleanup is required, model it as a separate Schedulable or monitoring job that polls AsyncApexJob for ABORTED status.

Common Patterns

Retry-on-Failure with Backoff Counter

When to use: A Queueable makes an external callout or complex DML that can fail transiently. You want automatic retry up to N times without manual re-queuing.

How it works:

1. Pass a retryCount integer into the Queueable constructor.
2. Inside execute(), call System.attachFinalizer(new MyFinalizer(jobPayload, retryCount)).
3. In the Finalizer's execute(), check ctx.getResult(). On UNHANDLED_EXCEPTION and retryCount < MAX_RETRIES, enqueue a new instance of the Queueable with retryCount + 1.
4. On retryCount >= MAX_RETRIES, write a failure record instead of re-enqueuing.

Why not try/catch inside execute(): A try/catch inside execute() only catches exceptions thrown by code in that block — governor-limit violations and some system exceptions escape it. A Finalizer provides an out-of-band, guaranteed callback even for unhandled exceptions that bypass catch blocks.

Failure Logging to Custom Object

When to use: You need an auditable record of every Queueable failure for operations monitoring, SLA reporting, or manual reprocessing.

How it works:

1. Attach a Finalizer that receives the job context (record IDs, batch key, etc.) from the parent Queueable constructor.
2. In execute(ctx), if ctx.getResult() == UNHANDLED_EXCEPTION, insert an Async_Job_Error__c (or equivalent) record with the job ID, exception message, stack trace, and payload snapshot.
3. Use the single Queueable enqueue slot only if retry is also needed; otherwise leave it unused.

Why not System.debug: Debug logs are transient and unavailable to non-admin users. A custom object record survives platform restarts and is queryable by monitoring tools.

Decision Guidance

Recommended Workflow

1. Confirm Queueable context — verify the failing async job is a Queueable, API v53+, and that abort-path behavior does not need to be covered by this Finalizer.
2. Choose Finalizer behavior — decide between retry, compensation DML, or both. If both, plan the single Finalizer class that handles them sequentially.
3. Design the retry ceiling — pick MAX_RETRIES (typically 3–5) and pass retryCount through the Queueable constructor so the Finalizer can increment and re-enqueue safely.
4. Implement System.Finalizer — create a class that implements System.Finalizer, receives the job payload via constructor, implements execute(FinalizerContext ctx), gates on ctx.getResult(), and enqueues at most one retry job.
5. Attach in execute() — call System.attachFinalizer(new MyFinalizer(...)) near the top of the parent Queueable's execute() method so it is registered before any code that might throw.
6. Test both SUCCESS and UNHANDLED_EXCEPTION paths — use Test.startTest() / Test.stopTest() to flush the queue; mock the failure by having the Queueable throw in test context, and assert the Finalizer's DML/enqueue behavior.
7. Review checklist — confirm no second attachFinalizer call, retry counter bounded, no attachFinalizer inside the Finalizer itself.

Review Checklist

• System.attachFinalizer() is called exactly once per Queueable execute() invocation
• Finalizer gates all compensation logic on ctx.getResult() == System.ParentJobResult.UNHANDLED_EXCEPTION
• Retry counter is passed via constructor and incremented before re-enqueuing; MAX_RETRIES ceiling is enforced
• The Finalizer enqueues at most one new Queueable job (throws AsyncException if you try more)
• No call to System.attachFinalizer() inside the Finalizer's own execute() method
• Tests cover both SUCCESS and UNHANDLED_EXCEPTION result paths
• Abort-path (if required) is handled by a separate mechanism — Finalizer does not fire on System.abortJob()

Salesforce-Specific Gotchas

1. Finalizer does not fire on System.abortJob() — If an admin or another job calls System.abortJob(parentJobId), the Finalizer is silently skipped. This is undocumented in some sources but confirmed in the official Apex Developer Guide. Any cleanup that must happen on abort needs a separate polling mechanism.
2. Parent transaction rollback is total — When the Queueable throws an unhandled exception, every DML operation in that transaction is rolled back. The Finalizer starts with a clean slate — it cannot read variables set in the parent, and it cannot "see" records that the parent tried but failed to commit.
3. One enqueue, no exceptions — Calling System.enqueueJob() more than once in a single Finalizer execute() call throws System.AsyncException immediately. Wrap the retry call in a conditional so it is only reached when retry is actually needed.
4. Finalizer exception is swallowed — If the Finalizer itself throws an unhandled exception, the platform logs it to ApexLog but does not propagate it anywhere visible. There is no secondary Finalizer. Build explicit logging inside the Finalizer's own execute() using a try/catch wrapper.

Output Artifacts

Related Skills

• apex-queueable-patterns — foundational Queueable design; use alongside this skill for the parent job structure
• apex-batch-chaining — for batch-to-batch chaining; Finalizers do not apply to Batch jobs
• apex-limits-monitoring — for monitoring Apex governor limits that might cause the Queueable to fail in the first place