Move from n8n Cloud to a dedicated instance
Move n8n Cloud workflows to a dedicated instance with credential reauthorization, trigger ownership, execution reconciliation and a reversible cutover plan.
Last updated
In short
- Workflow export is not a complete instance or credential backup.
- Only one environment should own each live trigger during cutover.
- Reconcile accepted events before replaying interrupted executions.
On this page (7)
Migration plans · Part of n8n
Migrate the runtime responsibilities as well as the workflows
Moving from n8n Cloud to a dedicated instance changes who owns upgrades, availability, backups, credentials, networking and incident response. The workflow graph is only part of the migration. A successful import can still fail when an OAuth callback changes or when both environments process the same scheduled event.
This is a documented reference migration plan, not a lab-validated export/import result. Confirm the source release, target release, node versions and target edition before moving data. Review the applicable n8n licence and commercial service arrangement for the intended deployment.
Build an inventory with transfer fidelity
| Item | Migration treatment | Acceptance evidence |
|---|---|---|
| Workflow definitions | Export/import through a supported method | Nodes, expressions and connections match |
| Credentials | Recreate or migrate only through supported secure mechanisms | Every destination authenticates successfully |
| OAuth grants | Reauthorize and update registered callback URLs | Fresh and refreshed access work |
| Webhooks | Update public URL and upstream registration | Exactly one intended receiver handles events |
| Schedules and polling | Transfer active ownership at cutover | No duplicate or missing interval |
| Execution history | Decide retention/export separately | Required evidence remains accessible |
| Binary files and static state | Inventory and handle explicitly | Representative execution has all required data |
| Users, projects and sharing | Recreate or use supported migration coverage | Least-privilege ownership preserved |
The workflow export documentation describes JSON and newer package-based options. Package functionality is marked Preview in the current documentation, so verify its exact coverage and behavior before depending on it. A portable format being available does not establish that every instance-level setting transfers.
The Cloud download guide states that its workflow backups do not include credentials and notes instance-specific export availability. Obtain a usable export while the source service remains accessible; do not schedule cancellation before verifying it.
Protect the exported material
Workflow JSON can contain credential names, identifiers and hard-coded authentication headers. Review exports before sharing them with a migration team or placing them in version control. Store sensitive exports in controlled storage with a deletion date and restricted access.
Create a credential register containing purpose, owner, destination, scope, expiry and reauthorization method, without copying secret values into the register. Use separate credentials for the target pilot where possible. This makes it easier to test without revoking the source’s working access prematurely.
Prepare an inactive target
Deploy the selected n8n release with its database, encryption key, public HTTPS URL and backup process. Import workflows with live triggers disabled. Check community or custom nodes for compatibility, source trust and installation requirements. A node available in one environment may require separate approval or packaging in the other.
Verify timezone settings, environment variables, file paths and network allowlists. A workflow that used an external public service may now reach it from a different egress address. OAuth applications may require the new callback URI before reauthorization works.
If the target uses queue mode, validate binary storage and worker behavior separately through the queue architecture. Do not combine a migration with an unmeasured scale redesign unless both are included in the acceptance scope.
Rehearse with synthetic events
Choose one workflow from each trigger class: webhook, schedule, polling and manually started operation. Use synthetic records with stable business IDs and direct outputs to test destinations.
| Scenario | Required result |
|---|---|
| Valid event | Correct destination record and mapped fields |
| Duplicate event | No duplicate business effect |
| Expired credential | Visible failure and bounded recovery procedure |
| Destination timeout after acceptance | Reconciliation before retry |
| Binary attachment | Correct content and filename at destination |
| Subworkflow invocation | Correct target reference and permissions |
| Time-based trigger | Expected timezone and schedule |
| Unauthorized operator | Cannot access credentials or modify protected workflow |
Compare outputs with the source using the same fixtures. Reconcile workflow count, node types, credential references and ownership, then inspect a sample of expressions and error paths. Matching counts alone cannot detect a changed formula or an incorrect endpoint.
Cut over one trigger owner at a time
Before cutover, record the final export revision and the last accepted source event or polling cursor. Pause source triggers, allow or reconcile in-flight executions, then enable the corresponding target triggers. Update upstream webhook destinations and verify delivery using a unique synthetic marker.
For polling systems, define the overlap window and deduplication rule. For schedules, record which environment owns the next scheduled run. Keep a ledger of accepted, completed and unresolved business events across both systems. This is more reliable than assuming an empty execution screen means all work finished.
Roll back with event reconciliation
If the target fails acceptance, disable its triggers before reactivating the source. Preserve events received and external actions performed during the target interval. Reconcile those IDs against the source so replay does not duplicate invoices, messages or account creation.
Retain the source subscription and configuration for the agreed rollback window. Back up the target database, encryption key references and workflow configuration after acceptance. Cancel or remove the source only when execution reconciliation, credential ownership and operational handover are complete. The migration outcome is a working, recoverable service with clear trigger ownership—not merely a set of imported JSON files.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
