n8n v1.0 migration guide#
This document provides a summary of what you should be aware of before updating to version 1.0 of n8n.
The release of n8n 1.0 marks a milestone in n8n's journey to make n8n available for demanding production environments. Version 1.0 represents the hard work invested over the last four years to make n8n the most accessible, powerful, and versatile automation tool. n8n 1.0 is now ready for use in production.
This release introduces semantic versioning. This allows n8n to signal backwards-incompatible changes directly in the version number, making it easier to update n8n safely.
From n8n 1.0 onwards, releases will follow the pattern MAJOR.MINOR.PATCH. Version numbers increment as follows:
- MAJOR version when making incompatible changes which potentially require user action
- MINOR version when adding functionality in a backward-compatible manner
- PATCH version when making backward-compatible bug fixes
Python support in the Code node#
n8n 1.0 introduces a new execution order for multi-branch workflows:
In multi-branch workflows, n8n needs to determine the order in which to execute nodes on branches. Previously, n8n executed the first node of each branch, then the second of each branch, and so on (breadth-first). The new execution order ensures that each branch executes completely before starting the next one (depth-first). Branches execute based on their position on the canvas, from top to bottom. If two branches are at the same height, the leftmost one executes first.
n8n used to execute multi-input nodes as long as they received data on their first input. Nodes connected to the second input of multi-input nodes automatically executed regardless of whether they received data. The new execution order introduced in n8n 1.0 simplifies this behavior: Nodes are now executed only when they receive data, and multi-input nodes require data on at least one of their inputs to execute.
Your existing workflows will use the legacy order, while new workflows will execute using the v1 order. You can configure the execution order for each workflow in workflow settings.
MySQL and MariaDB#
n8n will remove support for MySQL and MariaDB as storage backends in a future version of n8n. These database systems are used by only a few users, yet they require continuous development and maintenance efforts. n8n recommends migrating to PostgreSQL for better compatibility and long-term support.
EXECUTIONS_PROCESS and "own" mode#
Previously, you could use the
EXECUTIONS_PROCESS environment variable to specify whether executions should run in the
main process or in their
own processes. This option and
own mode are now deprecated and will be removed in a future version of n8n. This is because it led to increased code complexity while offering marginal benefits. Starting from n8n 1.0,
main will be the new default.
Note that executions start much faster in
main mode than in
own mode. However, if a workflow consumes more memory than is available, it might crash the entire n8n application instead of just the worker thread. To mitigate this, make sure to allocate enough system resources or configure queue mode to distribute executions among multiple workers.
When using Docker-based deployments, the n8n process is now run by the user
node instead of
root. This change increases security.
If permission errors appear in your n8n container logs when starting n8n, you may need to update the permissions by executing the following command on the Docker host:
We have removed the Debian and RHEL images. If you were using these you need to change the image you use. This shouldn't result in any errors unless you were making a custom image based on one of those images.
The entrypoint for the container has changed and you no longer need to specify the n8n command. If you were previously running
n8n worker --concurrency=5 it's now
Workflow failures due to expression errors#
Workflow executions may fail due to syntax or runtime errors in expressions, such as those that reference non-existent nodes. While expressions already throw errors on the frontend, this change ensures that n8n also throws errors on the backend, where they were previously silently ignored. To receive notifications of failing workflows, n8n recommends setting up an "error workflow" under workflow settings.
Mandatory owner account#
This change makes User Management mandatory and removes support for other authentication methods, such as BasicAuth and External JWT. Note that the number of permitted users on n8n.cloud or custom plans still varies depending on your subscription.
Directory for installing custom nodes#
n8n will no longer load custom nodes from its global
node_modules directory. Instead, you must install (or link) them to
~/.n8n/custom (or a directory defined by
CUSTOM_EXTENSION_ENV). Custom nodes that are npm packages will be located in
If you have custom nodes that were linked using
npm link into the global
node_modules directory, you need to link them again, into
N8N_PUSH_BACKEND environment variable can be used to configure one of two available methods for pushing updates to the user interface:
websocket. Starting with n8n 1.0,
websocket is the default method.
Date transformation functions#
Date or a Luxon
DateTime object. With the new behavior, the return type always matches the input. If you call a date transformation function on a
Date, it returns a
Date. Similarly, if you call it on a
DateTime object, it returns a
To identify any workflows and nodes that might be impacted by this change, you can use this utility workflow.
For more information about date transformation functions, please refer to the official documentation.
Execution data retention#
Starting from n8n 1.0, all successful, failed, and manual workflow executions will be saved by default. These settings can be modified for each workflow under "Workflow Settings," or globally using the respective environment variables. Additionally, the
EXECUTIONS_DATA_PRUNE setting will be enabled by default, with
EXECUTIONS_DATA_PRUNE_MAX_COUNT set to 10,000. These default settings are designed to prevent performance degradation when using SQLite. Make sure to configure them according to your individual requirements and system capacity.
request library has been deprecated for some time now. As of n8n 1.0, the ability to fall back to it in the HTTP Request node by setting the
N8N_USE_DEPRECATED_REQUEST_LIB environment variable has been fully removed. The HTTP Request node will now always use the new
If you build custom nodes, refer to HTTP request helpers for more information on migrating to the new interface.
As of version 0.227.0, n8n has renamed the
WEBHOOK_TUNNEL_URL configuration option to
WEBHOOK_URL. In n8n 1.0,
WEBHOOK_TUNNEL_URL has been removed. Update your setup to reflect the new name. For more information about this configuration option, refer to the docs.
Remove Node 16 support#
n8n now requires Node 18 or above.
Updating to n8n 1.0#
- Create a full backup of n8n.
- n8n recommends updating to the latest n8n 0.x release before updating to n8n 1.x. This will allow you to pinpoint any potential issues to the correct release. Once you have verified that n8n 0.x starts up without any issues, proceed to the next step.
- Carefully read the Deprecations and Breaking Changes sections above to assess how they may affect your setup.
- Update to n8n 1.0:
- During beta (before July 24th 2023): If using Docker, pull the
- After July 24th 2023: If using Docker, pull the
- During beta (before July 24th 2023): If using Docker, pull the
- If you encounter any issues, redeploy the previous n8n version and restore the backup.
If you encounter any issues during the process of updating to n8n 1.0, please seek help in the community forum.
We would like to take a moment to express our gratitude to all of our users for their continued support and feedback. Your contributions are invaluable in helping us make n8n the best possible automation tool. We're excited to continue working with you as we move forward with the release of version 1.0 and beyond. Thank you for being a part of our journey!