n8n-nodes-s3-execution-backup

n8n community node for automated daily backups of execution data to AWS S3.

Features

• ✅ Smart Deduplication - Two-layer strategy (HeadObject + state file)
• ✅ Long-Running Workflows - Daily re-snapshots for waiting executions
• ✅ Relationship Tracking - Parent-child executions and retry chains
• ✅ Scalable - Designed for 100,000+ executions/day
• ✅ Debug-Optimized - JSON with error summaries at the top
• ✅ Production-Ready - Rate limiting, error logging, encryption

Installation

npm install n8n-nodes-s3-execution-backup

Quick Start

1. Add credentials:

   • n8n API Key (from your n8n instance settings)
   • AWS S3 credentials (Access Key ID, Secret Access Key)

2. Create workflow:

   Schedule Trigger (cron: 0 1 * * *)
     └─> S3 Execution Backup
           - dateMode: yesterday
           - s3Bucket: my-n8n-backups
           - includeFullData: true

3. Run manually first to verify setup

Configuration

Required Parameters

| Parameter | Description | | ---------------- | ------------------------------------------------------- | | n8n API | Credential with API key | | n8n Base URL | Your n8n instance URL (e.g., https://n8n.example.com) | | AWS S3 | Credential with AWS keys | | S3 Bucket | Target S3 bucket name |

Optional Parameters

| Parameter | Default | Description | | --------------------- | ------------- | ---------------------------- | | Date Mode | yesterday | Which executions to back up | | Timezone | UTC | Timezone for date boundaries | | S3 Prefix | n8n-backups | S3 key prefix | | S3 Partitioning | hour | Folder organization | | Include Full Data | true | Include node input/output | | Compress Output | false | Gzip compression | | Manifest Format | jsonl | Streaming JSONL format |

See PLAN-FINAL.md for complete parameter reference.

S3 Structure

s3://your-bucket/n8n-backups/
  2026-03-01/
    executions/
      10/  ← Hour-based partitions
        execution_12345_success.json
        execution_12346_error.json
        execution_12347_waiting_snapshot.json
    workflows/
      workflow_abc123.json
    manifest.jsonl
    manifest-summary.json
    .state/
      backup-state.json

Performance & Cost

At 100,000 executions/day:

• Backup time: ~2.5 hours
• Storage: ~$69/month (with lifecycle: ~$55/month)
• API costs: ~$16/month
• Total: ~$85/month

Smaller deployments (1,000/day): ~$5-10/month

Known Limitations

Parent-Child Execution Relationships

Current Implementation (v1.0):

• Each execution is backed up as a separate file
• Parent execution IDs are recorded in child execution metadata
• Child execution IDs are listed in parent execution metadata
• Execution tree depth is calculated and stored

Not Yet Implemented:

• Full recursive tree resolution across multiple backup dates
• Automatic cross-linking of parent-child files when they span different backup runs
• Deep execution tree visualization beyond shallow metadata

Workaround:

• Parent and child execution IDs are stored in the metadata
• You can manually reconstruct relationships by matching IDs across backup files
• For workflows with complex sub-workflow chains, consider running backups more frequently to keep related executions in the same backup run

Planned for v2.0:

• Full recursive tree resolution
• Cross-date parent-child linking
• Execution graph export format

Retry Chain Tracking

Retry chains are fully tracked via retryOf, retriedBy, and retryChainRoot fields. This limitation only affects parent-child sub-workflow relationships.

Documentation

• PLAN-FINAL.md - Complete technical specification
• SUMMARY.md - Executive summary
• CHANGELOG.md - Version history

Supported n8n Versions

• n8n >= 1.0.0
• Node.js >= 18.0.0

Development

# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

License

MIT

Support

• Report issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Built with ❤️ for the n8n community