Automation
n8n 3.0 Breaking Changes and v2.48.7: Preparing Self-Hosted Workflows for Docker-Only Execution
As n8n ships maintenance release 2.48.7 on November 20, 2026 ahead of the n8n 3.0 stable launch, self-hosted teams face mandatory Docker deployment, removed legacy nodes, stricter 60-second runner timeouts, and tightened SSRF and Slack security defaults. Here is how to audit instances with the Migration Report.
10 min read
n8n 3.0 Breaking Changes and v2.48.7: Preparing Self-Hosted Workflows for Docker-Only Execution
Executive Summary
- Latest Release Cadence (November 20, 2026): While
n8n 3.0.0remains in early access ahead of an expected early December 2026 stable launch, n8n shipped maintenance releasen8n@2.48.7on November 20, 2026 alongside betan8n@2.49.3and legacy maintenance releasen8n@1.123.100, giving self-hosted operators a narrow window to complete pre-upgrade audits. - Docker-Only Self-Hosting: According to the n8n v3.0 Breaking Changes documentation, version 3.0 ends support for
npmandnpx n8ninstallations and stops publishing a runnablen8npackage to npm, making Docker (or Kubernetes/Helm) mandatory for self-hosted deployments. - Hard Removals vs. Silent Behavior Shifts: Version 3.0 deletes dozens of deprecated nodes (including
Function,Item Lists,Cron,Interval, and v1AI Agentmodes) that prevent affected workflows from activating, while silently altering multi-outputAlways Output Databehavior,Gmail Triggerpolling, andChat TriggerWebSocket framing. - Stricter Runtime & Security Defaults: Default
N8N_RUNNERS_TASK_TIMEOUTdrops from 300 seconds to 60 seconds, unverified community packages default to disabled,Compressionnode limits shrink to 256 MiB and 1,000 entries, Slack triggers require a signing secret, and upgrades from2.xto3.0are strictly one-way without a database backup.
What Changed in n8n 2.48.7 and the 3.0 Architecture
On November 20, 2026, the n8n engineering team published three coordinated releases on GitHub Releases: stable n8n@2.48.7 (commit 86dff76), pre-release beta n8n@2.49.3 (commit df32f5e), and 1.x maintenance build n8n@1.123.100 (commit 6a8407b). In 2.48.7, two targeted reliability fixes landed: core now ends the memory guard hold when a hold-limit stop frees no memory (#44463), and scripting nodes store plain input data in their error output (#44530). In 2.49.3, the HTTP Request node gained improved handling for empty response bodies during pagination (#44443).
These point releases arrive as platform teams prepare for n8n 3.0, whose early access breaking changes were documented in the n8n Changelog on October 29, 2026. As summarized in AY Automate's November 10, 2026 upgrade analysis and Pulsar Forge's November 19, 2026 field guide, 1.x support ends on December 31, 2026 with no direct upgrade path to 3.0, whereas the 2.x branch will continue receiving security and critical bug fixes for 12 months after 3.0 reaches stable availability.
flowchart TD
A[Current n8n Instance] --> B{Current Major Version?}
B -->|1.x EOL Dec 31, 2026| C[Upgrade to Latest 2.x First]
B -->|2.x Stable e.g. 2.48.7| D[Run Settings > Migration Report]
C --> D
D --> E{Deployment Method?}
E -->|npm or npx n8n| F[Migrate to Docker Compose + Postgres]
E -->|Docker / K8s / Cloud| G[Fix Blocked & Failing Nodes in 2.x]
F --> G
G --> H[Full DB + ~/.n8n Backup]
H --> I[Stage & Replay on 3.x Container]
I --> J[Cut Over Production to Pinned 3.0 Tag]Mandatory Docker Deployment and Storage Path Changes
The largest infrastructure shift in n8n 3.0 affects teams running bare-metal or VM processes via npm install -g n8n or npx n8n. Per the n8n v3.0 Breaking Changes, n8n 3.0 no longer publishes a runnable package to npm and requires a Docker-based deployment for self-hosting (Kubernetes and Helm deployments remain unaffected by the Docker CLI requirement, though all workflow and configuration rules still apply). Community node developers using n8n-node dev are similarly affected: the CLI now launches the official container image via Docker or Podman rather than npx, and stores test data in per-image container volumes (n8n-node-cli-data-<image>) rather than ~/.n8n-node-cli/.n8n because n8n database migrations only move forward.
On first boot, n8n 3.0 also renames ~/.n8n/binaryData to ~/.n8n/storage and removes N8N_MIGRATE_FS_STORAGE_PATH. Crucially, if both directories exist on disk simultaneously, n8n 3.0 refuses to start rather than guessing which directory holds active state. Operators with explicit Docker volume mounts pointing to ~/.n8n/binaryData must either update their mount target to ~/.n8n/storage or set N8N_STORAGE_PATH explicitly before starting the container.
Removed Nodes, Helpers, and Legacy AI Modes
In n8n 3.0, workflows referencing removed nodes fail at execution time, and published workflows using those nodes will not activate on startup—meaning webhooks and scheduled triggers silently stop firing. The official breaking-changes list retires:
- Core & Scripting Nodes: Legacy
FunctionandFunction Item(replaced by theCodenode in Run Once for All Items and Run Once for Each Item modes),Item Lists(split intoSplit Out,Aggregate,Sort,Limit,Remove Duplicates, andSummarize),CronandInterval(replaced bySchedule Trigger),Workflow Trigger(replaced byn8n Trigger), andAI Transform(must be converted toCodevia the Migration Report prior to upgrade). - File & Parsing Nodes:
HTML Extract,iCalendar,Convert to/from binary data,Read Binary File,Read Binary Files,Write Binary File, andRead PDF(replaced byHTML,Convert to File,Extract from File, andRead/Write Files from Disk). - AI & Vector Store Nodes: Legacy
OpenAI,OpenAI Assistant,OpenAI Model, legacyHTTP Request Tool,Manual Chat Trigger,Chat Messages Retriever,LangChain Code(no direct replacement),MotorheadandZepmemory/vector nodes (no direct replacement),SerpApi (Google Search)(no direct replacement; useHTTP Requestas a tool),Binary Input Loader,JSON Input Loader,GitHub Document Loader, and splitInsert/Loadvector store nodes for Pinecone, Supabase, and In-Memory stores. - Node Versions & Helpers:
AI Agentv1 (removingSQL Agent,Conversational Agent,OpenAI Functions Agent,Plan and Execute Agent, andReAct Agentin favor ofTools Agent),Edit Imagev1 and v1.1 (v2 changes the underlying image library, dropping Blur Sigma and ignoring PNG/TIFF Quality),Execute Sub-workflowLocal File and URL sources,$getPairedItem(replaced by$('<node-name>').item,.itemMatching(), and.pairedItem()), and$evaluateExpression()inside JavaScriptCodenodes.
Silent Behavior Changes That Do Not Throw Errors
As Pulsar Forge and AY Automate highlight, the highest operational risk in 3.0 lies in nodes that continue executing without errors while producing different downstream results:
- Multi-Output
Always Output Data: On branching nodes such asIfandSwitch, enablingAlways Output Datanow emits an empty item only when every output branch is empty, preventing unintended fallback branches from firing. - Gmail Trigger Consolidation: Versions
1.0through1.3of theGmail Triggernode now execute with1.4semantics—capping polls viaMax Emails per Poll(default10, max50), skipping drafts unlessInclude Draftsis enabled, and ignoring sent or scheduled emails outside the inbox. - Chat Trigger WebSocket Framing: In
Using Response Nodesmode, the Chat Trigger WebSocket now sends structured JSON frames (heartbeat,continue,error,message,with-buttons) and expects{"type": "heartbeat-ack"}responses, requiring custom clients to parse JSON and embedded@n8n/chatwidgets to be at version1.31.0or newer. - Webflow OAuth2 Scopes: The
Legacytoggle defaults tofalse, causing reconnected credentials without an explicit saved toggle to request Webflow v2 API scopes (cms:read,cms:write,sites:read,forms:read).
Reliability, Security, and Performance Trade-Offs
Version 3.0 shifts n8n's operational posture toward stricter isolation and bounded resource consumption. While these defaults reduce blast radius on multi-tenant or public-facing instances, they introduce immediate compatibility cliffs for long-running scripts, large archive pipelines, and internal network calls.
| Parameter / Control | n8n 2.x Default | n8n 3.0 Default | Operational Impact & Mitigation |
|---|---|---|---|
| Deployment Runtime | npm, npx, Docker, K8s |
Docker / K8s only | Bare-metal npm installs must migrate to Docker Compose |
N8N_RUNNERS_TASK_TIMEOUT |
300 seconds (5 min) |
60 seconds (1 min) |
Long Code node scripts time out; set env var explicitly |
N8N_UNVERIFIED_PACKAGES_ENABLED |
true |
false |
Custom/unverified npm community nodes stop loading |
| Compression Decompress Cap | 2 GiB / 5,000 files |
256 MiB / 1,000 files |
Large zip pipelines fail unless overridden via env vars |
| Binary Data Mode | default (in-memory) |
filesystem |
In-memory mode removed; verify disk/S3/DB capacity |
| Encryption Key Rotation | Opt-in | Enabled by default | Existing credentials remain readable; back up DB + key |
| Slack API Credential | Signing secret optional | Signing secret mandatory | Slack Trigger workflows fail to activate without secret |
| SSRF Default Block List | Standard private ranges | Adds ::/128, 100.64.0.0/10, 2002::/16, 64:ff9b::/96 |
CGNAT/NAT64 internal calls fail unless allowlisted |
Security Hardening: Slack, SSRF, and Secrets
In n8n 3.0, security controls move from opt-in to fail-closed. Any workflow using a Slack Trigger node will refuse to publish—and previously published workflows will fail to activate on startup—until the Signature Secret field on the Slack API credential is populated from the Slack app's Basic Information settings. Similarly, N8N_SSRF_PROTECTION_ENABLED=true with N8N_SSRF_BLOCKED_IP_RANGES=default now blocks carrier-grade NAT (100.64.0.0/10), IPv6 unspecified (::/128), 6to4 (2002::/16), and NAT64 (64:ff9b::/96) ranges. Teams calling internal microservices over Tailscale or CGNAT-backed VPNs must explicitly allowlist those ranges via N8N_SSRF_ALLOWED_IP_RANGES or N8N_SSRF_ALLOWED_HOSTNAMES rather than removing default from the block list.
On n8n Enterprise, the Enable external secrets for project roles toggle is removed, granting project editors and admins external-secrets access by default unless custom project roles are configured beforehand. Encryption key rotation is also enabled by default (manageable under Settings > Data Encryption Keys), re-encrypting records lazily on update while preserving backward readability.
Performance, Queue Workers, and Memory Limits
Three runtime changes directly affect throughput and worker sizing:
- Task Runner Timeout (
60s): ReducingN8N_RUNNERS_TASK_TIMEOUTfrom300seconds to60seconds prevents runaway JavaScript or PythonCodenodes from starving runner pools, but batch data transformations or synchronous API loops insideCodenodes will now abort at the one-minute mark unless the timeout is raised. - Mandatory Worker Offload for Manual Runs:
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERSis removed; in queue mode, manual test executions in the editor now always dispatch to queue workers. Platform teams must provision additional worker RAM/CPU headroom so interactive debugging does not contend with production webhook traffic. - Removed Pre-Execute Failure Records:
N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTIONis removed. If aworkflow.preExecuteexternal hook throws, no execution record is created, requiring teams that monitored failed pre-execute records to emit alerts directly from the hook.
Practical Migration Workflow and Operational Gotchas
Because n8n 2.x receives security and critical bug fixes for 12 months after 3.0 stable ships, production teams should not rush early-access 3.0 builds into production. Instead, use the current 2.48.7 stable release to complete all preparatory remediation without downtime.
Step 1: Audit with the Built-In Migration Report
Available on 2.39+ under Settings > Migration Report (and improved in 2.45.4–2.46.3 with project filters, owner assignment, CSV export, and How to fix panels), the report categorizes findings into five severity tiers: Upgrade blocked, Executions will fail, Executions might fail, Behavior changes, and Capability removed. Automated migrations inside the report save fixes as new workflow versions without disturbing currently published live versions, allowing teams to remediate Function, Cron, Item Lists, and AI Transform nodes incrementally on 2.48.7.
Step 2: Pin Docker Compose and Explicit Overrides
When preparing your staging Docker Compose stack for 3.0 testing, pin explicit image tags rather than latest, update volume mounts from ~/.n8n/binaryData to ~/.n8n/storage, and declare overrides for any tightened 3.0 defaults your workloads depend on:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:2.48.7 # Pin exact version; test 3.x on staging first
environment:
- DB_TYPE=postgresdb
- N8N_DEFAULT_BINARY_DATA_MODE=filesystem
- N8N_RUNNERS_TASK_TIMEOUT=300 # Override 3.0's new 60s default if needed
- N8N_UNVERIFIED_PACKAGES_ENABLED=true # Only if unverified community nodes are required
- N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=2147483648
- N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=5000
- DB_PING_TIMEOUT_MS=5000 # Replaces removed N8N_DB_PING_TIMEOUT
volumes:
- n8n_data:/home/node/.n8n # Ensure no conflicting binaryData + storage dirs exist
Step 3: Back Up Before the One-Way Cutover
There is no rollback from n8n 3.0 to 2.x. Before pulling a 3.x tag on staging or production, back up both the PostgreSQL/SQLite database and the entire ~/.n8n directory (or N8N_ENCRYPTION_KEY), because saved credentials cannot be decrypted without the instance encryption key.
Frequently Asked Questions
Should production teams upgrade to n8n 3.0 right now?
No. As of November 20–21, 2026, n8n 3.0 is an early access release with stable availability expected in early December 2026, while n8n@2.48.7 is the current stable release. Teams should stay on 2.48.7, complete all Settings > Migration Report fixes, and validate workflows on a 3.x staging container before cutting over production.
Can self-hosted instances still run n8n 3.0 via npm or npx?
No. n8n 3.0 drops support for npm and npx n8n installations and does not publish a runnable n8n package to npm. Self-hosted users must migrate to a Docker-based deployment (such as Docker Compose with PostgreSQL) or Kubernetes/Helm before upgrading.
Can I roll back from n8n 3.0 to 2.x if a workflow breaks?
No. Database migrations in n8n only move forward, and downgrading from 3.0 to 2.x is not supported. Returning to 2.x requires restoring a full pre-upgrade database backup alongside your ~/.n8n encryption key.
How long will n8n 2.x and 1.x remain supported?
n8n 1.x (currently at 1.123.100) reaches end-of-life on December 31, 2026, and there is no direct upgrade path from 1.x to 3.0. n8n 2.x will receive security and critical bug fixes for 12 months after n8n 3.0 reaches stable release.
What silently breaks in n8n 3.0 even if the Migration Report is clean?
The Migration Report cannot detect every runtime shift. Teams must manually verify Slack API credentials (adding the Signing Secret), check internal HTTP calls against the expanded SSRF block list (such as 100.64.0.0/10), confirm Code node tasks finish within 60 seconds, and verify @n8n/chat embeds are at version 1.31.0 or later.
Sources
- n8n Releases — GitHub (
n8n@2.48.7,n8n@2.49.3,n8n@1.123.100) — November 20, 2026 - v3.0 Breaking Changes | Changelog | n8n Docs — October 29, 2026
- n8n update: What changes in n8n 3.0 for your workflows — Pulsar Forge — November 19, 2026
- n8n 3.0 Upgrade Guide: Breaking Changes and Checklist — AY Automate — November 10, 2026