Job Processing Reliability
How Queuert keeps jobs safe when errors occur — transactional completion, automatic rollback, and rescheduling.
When your code throws during job processing, your transaction rolls back any partial work and the worker reschedules the job with backoff. This happens automatically — no defensive error handling is needed inside your handler.
This page covers the engine's safety guarantees. For user-level error strategies (discriminated unions, compensation, rescheduling), see Error Handling. For the architectural overview, see Job Processing.
The Short Version
- Your handler opens a transaction with your database client and calls
completeinside it. - If anything throws before that transaction commits, your database client rolls back your SQL together with the job's completion.
- If no
completecommitted, the worker reschedules the job with exponential backoff. - This works regardless of where the error occurs — before your transaction or inside it. Once
completehas committed, the outcome stands.
The rest of this page walks through each scenario with code examples.
Error Before the Transaction
Work before your transaction — reads, external API calls — runs without a transaction. If it throws, nothing was written and the job is rescheduled using the first backoffConfig set on the processor, its processor registry or the worker, or else the default exponential backoff.
src/error-recovery.ts
"charge-payment": {
backoffConfig: { initialDelayMs: 1000, multiplier: 2, maxDelayMs: 60_000 },
attemptHandler: async ({ job, complete }) => {
const order = orders.get(job.input.orderId);
if (order === undefined) throw new Error("Order not found");
const { paymentId } = await paymentApi.charge(job.id, order.amountCents);
return stateAdapter.withTransaction(async (txCtx) => {
orders.set(job.input.orderId, { ...order, paymentId });
return complete({ ...txCtx, output: { paymentId } });
});
},
},Because the external call runs before the transaction, the next attempt runs it again. Make external side effects idempotent: the payment API above receives job.id as its idempotency key, so the order is charged once however many attempts run.
Error Inside the Transaction
If your transaction callback throws, your database client rolls the transaction back — undoing any SQL you executed, the job completion, and any continuation jobs created via continueWith — and the job is rescheduled with backoff. In the example, updateBalance stands for an UPDATE guarded by a CHECK (balance >= 0) constraint: it throws when the balance would go negative, and its earlier writes in the transaction roll back.
src/error-recovery.ts
"transfer-funds": {
attemptHandler: async ({ job, complete }) =>
stateAdapter.withTransaction(async (txCtx) => {
updateBalance(txCtx, job.input.toAccountId, job.input.amountCents);
updateBalance(txCtx, job.input.fromAccountId, -job.input.amountCents);
return complete({ ...txCtx, output: { transferred: true } });
}),
},While the source account lacks the funds, every attempt credits the target account and then fails on the debit, so both writes roll back and the job keeps being rescheduled. Once the source account is topped up, the next attempt commits the transfer.
The same holds for a throw after complete returned but before the transaction commits: the completion is part of your transaction, so it rolls back together with your writes.
Intermediate Transactions
A handler can commit work in its own transactions before the one that calls complete. Those transactions are not tied to the attempt unless they call fence: if an error occurs after one commits (typically a failed external API call), the job is rescheduled with backoff, its side-effects persist, and the next attempt runs it again. Here the first transaction counts the sync start, so a failed external call leaves the item with two starts once the next attempt completes:
src/error-recovery.ts
"sync-item": {
attemptHandler: async ({ job, complete }) => {
const item = await stateAdapter.withTransaction(async () => {
const current = items.get(job.input.itemId)!;
const started = { ...current, syncStarts: current.syncStarts + 1 };
items.set(job.input.itemId, started);
return started;
});
const externalId = await externalApi.sync(job.input.itemId);
return stateAdapter.withTransaction(async (txCtx) => {
items.set(job.input.itemId, { ...item, externalId });
return complete({ ...txCtx, output: { externalId } });
});
},
},Note: Intermediate transactions without
fencecommit even if the attempt is later lost to another worker. Callfenceat the start of one to commit it only while the attempt owns the job, and design its side-effects to be safe to keep when the job is rescheduled.
Error After complete Committed
Once the transaction that called complete has committed, the outcome is final. If the handler throws afterwards, the error is reported as a worker error (workerError), but the completion is not rolled back and the job is not rescheduled. When the notification API below fails, the job stays completed on its first attempt:
src/error-recovery.ts
"notify-account": {
attemptHandler: async ({ job, complete }) => {
const result = await stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, output: { notified: true } }),
);
await notificationApi.send(job.input.accountId);
return result;
},
},Keep work that must succeed for the job to count as done inside the transaction (or before it). Work after the commit is your responsibility.
What This Means in Practice
- Any unhandled error before the commit → reschedule with backoff. Whether the error occurs before your transaction or inside it — the job is always rescheduled. Backoff follows the first
backoffConfigset on the processor, its processor registry or the worker, or else the default, which starts at 10s, doubles with each attempt and caps at 300s. A handler that returns without a committedcompleteis rescheduled the same way. - No corrupted state. Your transaction ensures that partial SQL work is never committed when an error occurs.
- No orphaned continuations. If
completewas called withcontinueWithand the transaction throws afterward, both the continuation job and the completion are rolled back. - Blocked jobs stay blocked. If a blocker job's completion is rolled back, dependent jobs remain correctly blocked.
- No lost-attempt writes.
completeonly writes while this attempt still owns the job. If the attempt was reclaimed and another worker took the job, or the job was completed or deleted elsewhere,completewrites nothing and throwsJobTakenByAnotherWorkerError,JobAlreadyCompletedErrororJobNotFoundError, so your transaction rolls back. Writes in your other transactions get the same guarantee when they callfencefirst. - No defensive
try/catchneeded. Let exceptions propagate naturally — the worker handles them. - Jobs are rescheduled indefinitely. There is no maximum attempt count. Use discriminated unions or compensation patterns to handle permanently failing jobs.
See examples/guides/src/error-recovery.ts for the runnable code. See also Error Handling for user-level error strategy, Timeouts for the worker lease, and Job Processing for the processing model.