The Sweeper Pattern: How I Reconcile Crashed n8n Jobs Without Guessing

Описание и применение

Паттерн Sweeper позволяет автоматически восстанавливать состояние задач в n8n, которые завершились сбоем, используя lease‑сроки и проверку внешних провайдеров.

Задача

Crashed n8n jobs leave rows in an ambiguous "claimed" state, making it unclear whether the external action (email, charge, webhook) succeeded.

Результат

Implemented a sweeper that reliably reconciles ambiguous job states, reducing duplicate external actions and providing a clear "review" state for human inspection.

Рабочий процесс

• Create jobs table with lease_seconds default 600
• Worker atomically claims a queued job by updating state to "claimed" and setting claimed_at
• Sweeper runs on schedule, selecting jobs where state is "claimed" and claimed_at is older than lease_seconds
• For each expired job, determine provider class and available handle
• If forced-unique provider with idempotency key or provider reference, re-drive or query provider to confirm success and set state to "done"
• If suggestion-key provider with deterministic handle, look up provider; if found set to "done", if not found after settle window set to "review"
• If suggestion-key provider with no handle, set to "review"
• Ensure single-flight by using a sweep_locks table or atomic claim on sweeper rows
• Handle kill scenarios by asserting provider-side counts and avoiding duplicate effects

Доказательства

A sweeper is a scheduled job that scans for work left in an ambiguous state and decides its fate.

Источник

Workers claim atomically — only the worker that gets the row proceeds:

Источник

And the sweeper touches only expired leases:

Источник

The lease is the line between "the worker is slow" and "the worker is dead." Ten minutes is my default.

Источник