Execution Retention Policy Setup
I’ve operated n8n in production environments where a single misconfigured retention setting silently consumed database storage until workflows slowed to a crawl.
Execution Retention Policy Setup defines how long n8n keeps execution data, ensuring operational visibility without sacrificing performance or database health.
How Execution Data Actually Works in n8n
Every workflow run in n8n generates execution data that includes status, timestamps, node outputs, and optionally full input/output payloads. This data is stored directly in the primary database, not in ephemeral memory or temporary logs. If retention is not controlled, execution records accumulate indefinitely and degrade query performance over time.
Retention is enforced globally at the instance level using environment variables, meaning the policy applies consistently across all workflows unless you introduce custom cleanup logic.
Why Retention Configuration Is Mandatory in Production
In real production workloads, execution volume scales faster than most teams expect. Webhooks, scheduled automations, and retries can generate thousands of executions per day. Without pruning, database tables grow continuously, backups slow down, and UI responsiveness suffers.
A correct retention policy protects three critical areas:
- Database performance under sustained execution load
- Disk usage predictability for cloud and VPS environments
- Operational clarity by preserving only actionable execution history
Execution Retention Controls Available in n8n
n8n exposes retention behavior exclusively through environment variables. These variables are evaluated continuously and enforced by the internal pruning process.
| Environment Variable | Function |
|---|---|
| EXECUTIONS_DATA_PRUNE | Enables automatic pruning of execution records |
| EXECUTIONS_DATA_MAX_AGE | Maximum age (in hours) an execution may exist before deletion |
| EXECUTIONS_DATA_PRUNE_MAX_COUNT | Maximum total number of executions retained |
| EXECUTIONS_DATA_SAVE_ON_SUCCESS | Controls persistence of successful executions |
| EXECUTIONS_DATA_SAVE_ON_ERROR | Controls persistence of failed executions |
| EXECUTIONS_DATA_SAVE_ON_PROGRESS | Controls intermediate execution state storage |
Recommended Production Configuration (Balanced)
This configuration preserves full visibility into failures while aggressively minimizing storage overhead from successful runs.
EXECUTIONS_DATA_PRUNE=true
This setup retains up to 14 days of execution history while preventing unbounded growth if execution volume spikes unexpectedly.
Age-Based vs Count-Based Retention
Age-based pruning removes executions once they exceed a defined lifespan, while count-based pruning enforces a hard cap on total records. n8n evaluates both independently, meaning whichever limit is reached first triggers deletion.
Relying on only one strategy creates blind spots. Age-only retention fails under sudden traffic bursts, while count-only retention may delete recent executions prematurely. Combining both provides deterministic control.
Common Failure Modes and How to Fix Them
Executions Disappear Earlier Than Expected
This typically occurs when the maximum execution count is reached before the age threshold. Increasing EXECUTIONS_DATA_PRUNE_MAX_COUNT or reducing execution volume resolves the issue.
Database Size Keeps Growing
Retention only applies to execution data, not binary payloads or external storage. Large file transfers can still inflate database size. Disable unnecessary output persistence and offload large payloads to object storage when possible.
Need Different Retention Rules per Workflow
n8n does not support per-workflow retention natively. The practical workaround is a scheduled cleanup workflow using the internal execution API to selectively delete older executions for specific workflows.
Operational Best Practices
- Review execution volume weekly and adjust retention thresholds proactively
- Store only error executions unless audit requirements demand otherwise
- Monitor database size and query latency, not just disk usage
- Apply retention changes during low-traffic deployment windows
Before rolling retention changes into production, double-check execution data limits and pruning behavior in the official n8n execution data documentation to avoid unexpected data loss or premature pruning.
FAQ
Does retention affect active executions?
No. Pruning only applies to completed executions. Active and running workflows are never interrupted.
Can retention be changed without restarting n8n?
No. Environment variables are read at startup, so a restart is required for changes to take effect.
Is execution data required for workflow retries?
Retries rely on runtime state, not historical execution records. Retention does not affect retry behavior.
Is retention enforced immediately?
Pruning runs continuously in the background. Deletions occur incrementally rather than in a single blocking operation.
Conclusion
Execution Retention Policy Setup is not an optimization detail—it is a foundational requirement for running n8n reliably at scale. When retention is configured deliberately, n8n remains fast, predictable, and operationally transparent even under sustained automation load.