Scheduling & CRON Tasks
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/scheduler/README.md
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts
- packages/frontend/editor-ui/src/features/agents/components/AgentTaskModal.vue
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts
Scheduling in n8n provides the logic to execute workflows and tasks at specific times or recurring intervals. The system uses a durable, cluster-safe scheduler that records upcoming runs in shared storage to ensure execution across restarts and multiple server instances.
Sources: packages/@n8n/scheduler/README.md:1-10, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:9-12
Durable Scheduler Architecture
The scheduler architecture separates the definition of a schedule from its concrete execution. This design prevents data loss during server crashes and coordinates work across a distributed cluster.
Core Concepts
- Job: A rule that defines when an event should happen, such as a cron expression or interval.
- Task: A concrete run produced from a Job, scheduled for one specific instant. Tasks are the units that the system claims, runs, retries, and cleans up.
Sources: packages/@n8n/scheduler/README.md:19-27
Components and Data Flow
The scheduler executes four background routines on repeating timers to manage the lifecycle of jobs and tasks.
The diagram shows the progression from rule definition to concrete task execution and maintenance.
Sources: packages/@n8n/scheduler/README.md:38-60
| Component | Responsibility |
|---|---|
| Planner | Claims jobs whose next run is due and computes future occurrences. It advanced the job's clock and records these as tasks. |
| Runner | Claims due tasks for the local server and arms precise in-memory timers. It calls the registered handler when the timer fires. |
| Recovery | Identifies tasks with expired leases left in a "running" state by crashed or stalled servers. It puts them back in line for retry. |
| Cleanup | Removes finished tasks from storage after a retention window passes. |
Sources: packages/@n8n/scheduler/README.md:62-84
Schedule Kinds
The scheduler supports four distinct recurrence patterns to handle different timing requirements.
| Kind | Description | Example |
|---|---|---|
cron | Fires at fixed clock times using standard syntax. It follows daylight-saving shifts. | 0 0 9 * * 1 (Mondays at 09:00) |
interval | Fires every N seconds of elapsed time. It ignores daylight-saving shifts. | Every 3600 seconds |
one_off | Fires once at a single instant and then expires. | 2026-01-01 00:00 |
recurring_cron | Combines a cron anchor with an "every N periods" filter. | Every 3 weeks on Monday |
Sources: packages/@n8n/scheduler/README.md:104-135
Recurring CRON Logic
Standard cron cannot express cadences that span cycles, such as "every 5 hours" or "every third Monday." The recurring_cron kind solves this by filtering candidates from a cron anchor. It keeps a candidate only if at least N periods have passed since the previous run.
Sources: packages/@n8n/scheduler/README.md:120-135
Task Lifecycle states
Tasks move through several states from creation to final deletion.
This state machine represents how the Runner and Recovery components transition tasks based on execution results.
Sources: packages/@n8n/scheduler/README.md:275-300
Misfires and Overlapping Executions
A misfire occurs when a run comes due while the instance is down. The job's misfire policy determines how the backlog is handled once the oldest overdue instant passes its grace window.
- Skip: Records nothing for the backlog; the rule resumes from the next future instant.
- Coalesce: Records one late run for the job to represent the whole backlog.
- Coalesce Owner: Records one late run for the entire owner (e.g., a trigger node) across all its jobs.
Sources: packages/@n8n/scheduler/README.md:139-165
Overlapping Execution Prevention
Overlapping executions occur when a new run starts before the previous run completes. To prevent this:
- Increase the interval to exceed the worst-case execution time.
- Implement a mutex or lock mechanism using n8n Data Tables.
- Add a check at the workflow start to verify if a "running" flag is set.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:15-18, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:114-118
Scheduling in Workflows
Workflows utilize scheduled triggers to automate recurring tasks.
Schedule Trigger Node
The Schedule Trigger node (n8n-nodes-base.scheduleTrigger) supports two primary modes:
- Interval Mode: Dropdowns for common schedules (minutes, hours, days).
- Cron Expression Mode: Standard 5-field or 6-field (including seconds) syntax.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:21-28, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:133-136
Wait Node
The Wait node (n8n-nodes-base.wait) pauses execution until a specific time or duration. Unlike the Schedule Trigger, it uses server system time and may ignore the workflow's timezone setting.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:33-35, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/scheduling.ts:121-125
Agent Task Scheduling
n8n Agents support scheduled tasks managed via the AgentTaskModal. Users can configure frequency (hourly, daily, weekly, monthly, custom), specific times, and timezones.
Sources: packages/frontend/editor-ui/src/features/agents/components/AgentTaskModal.vue:150-200
Timezone Handling
The UI determines the browser timezone for new tasks. If a task has no stored timezone, it follows the instance default. The scheduler sampled clock differences between the instance and the shared store to warn about clock-skew that might affect firing times.
Sources: packages/frontend/editor-ui/src/features/agents/components/AgentTaskModal.vue:108-115, packages/@n8n/scheduler/README.md:339-348
Conclusion
The n8n scheduling system provides a resilient framework for time-based automation. By using a durable storage model, it guarantees that tasks are claimed and executed even in distributed environments or after system failures. Developers should prioritize the durable scheduler's features, such as misfire policies and recurring cron filters, to build reliable, long-running workflows.
Sources: packages/@n8n/scheduler/README.md:1-15, packages/@n8n/scheduler/README.md:245-255