Upgrade Path

n8n 0.156.0 → 2.42.0

638 versions, 38 with breaking changes (2 repeat an earlier entry), the 2.0.0 upgrade guide, 0 required stops

Version by version, oldest first

0.157.0 – 0.164.1: no action items (13 versions)

0.165.0 2022-02-28

Breaking

What changed?

The Hive node now correctly rejects invalid SSL certificates when the "Ignore SSL Issues" option is set to False.

When is action necessary?

If you are using a self signed certificate with The Hive.

How to upgrade:

Go to the credentials for The Hive, Enable the "Ignore SSL Issues" option.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.165.0

0.165.1 – 0.170.0: no action items (8 versions)

0.171.0 2022-04-03

Breaking

What changed?

The GraphQL node now errors when the response includes an error.

When is action necessary?

If you are using the GraphQL node.

How to upgrade:

Go to the workflows that use the GraphQL node and adjust them to the new behavior. If you want to continue even on error, you can set "Continue on Fail" to true.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.171.0

0.171.1 – 0.197.1: no action items (52 versions)

0.198.0 2022-10-14

Breaking

What changed?

The Merge node list of operations was rearranged.

When is action necessary?

If you are using the overhauled Merge node and 'Merge By Fields', 'Merge By Position' or 'Multiplex' operation.

How to upgrade:

Go to the workflows that use the Merge node, select 'Combine' operation and then choose an option from 'Combination Mode' that matches an operation that was previously used. If you want to continue even on error, you can set "Continue on Fail" to true.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Breaking

  • The Merge node list of operations was rearranged.

Merge node: 'Combine' operation was added with 'Combine Mode' option, operations 'Merge By Fields', 'Merge By Position' and 'Multiplex' placed under 'Combine Mode' option. To update -go to the workflows that use the Merge node, select 'Combine' operation and then choose an option from 'Combination Mode' that matches an operation that was previously used. If you want to continue even on error, you can set "Continue on Fail" to true.

From github.com/n8n-io/n8n/blob/master/CHANGELOG.md

Full release notes for 0.198.0

0.198.1 – 0.201.0: no action items (6 versions)

0.202.0 2022-11-10

Breaking

What changed?

Switched from NPM to PNPM for development.

When is action necessary?

If you are contributing to n8n.

How to upgrade:

Make sure that your local development setup is up to date with the latest [Contribution Guide](../../CONTRIBUTING.md).

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.202.0

0.202.1 – 0.213.0: no action items (25 versions)

0.214.0 2023-02-03

Breaking

What changed?

Invalid Luxon datetimes no longer resolve to null. Now they throw the error invalid DateTime.

When is action necessary?

If you are relying on the above behavior, review your workflow to ensure you handle invalid Luxon datetimes.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.214.0

0.214.1 – 0.222.1: no action items (22 versions; 6 backports, released after the next line began, are not on this route)

0.222.2 – 0.222.3: released after 0.223.0; not on this route

0.223.0 2023-04-05

Breaking

What changed?

The minimum Node.js version required for n8n is now v16.

When is action necessary?

If you're using n8n via npm or PM2 or if you're contributing to n8n.

How to upgrade:

Update the Node.js version to v16 or above.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.223.0

0.224.0 – 0.225.2: no action items (5 versions; 0.224.2 – 0.224.4, released after 0.225.0, are not on this route)

0.226.0 2023-04-26

Breaking

What changed?

The extractDomain and isDomain are now also matching localhost, domains without protocol and domains with query parameters. The extractUrl and isUrl are additionally also matching localhost and domains with query parameters.

When is action necessary?

If you're using the extractDomain or isDomain functions and expect them to not match localhost, domains without protocol and domains with query parameters.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.226.0

0.226.1 – 0.231.1: no action items (12 versions; 2 backports, released after the next line began, are not on this route)

0.231.2 – 0.231.3: released after 0.232.0; not on this route

0.232.0 2023-06-07

Breaking

What changed?

Due to Node.js/OpenSSL upgrade, the following crypto algorithms are not supported anymore.

  • RSA-MD4
  • RSA-MDC2
  • md4
  • md4WithRSAEncryption
  • mdc2
  • mdc2WithRSA

When is action necessary?

If you're using any of the above mentioned crypto algorithms in Crypto node in any of your workflows, then please update the algorithm property in the node to one of the supported values.

What changed?

The LoneScale List node has been renamed to LoneScale.

When is action necessary?

If you have used the LoneScale List node in any of your workflows.

How to upgrade:

Update any workflows using LoneScale List to use the updated node.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.232.0

0.233.0 – 0.233.1: no action items (2 versions)

0.234.0 2023-06-22

Breaking

What changed?

This release introduces two irreversible changes:

  • The n8n database will use strings instead of numeric values to identify workflows and credentials
  • Execution data is split into a separate database table

When is action necessary?

It will not be possible to read a n8n@0.234.0 database with older versions of n8n, so we recommend that you take a full backup before migrating.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 0.234.0

0.234.1 – 0.237.0: released after 1.0.0; not on this route

1.0.0 2023-06-27

Breaking

What changed?

The minimum Node.js version required for n8n is now v18.

When is action necessary?

If you're using n8n via npm or PM2 or if you're contributing to n8n.

How to upgrade:

Update the Node.js version to v18 or above.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Breaking

  • core Docker containers now run as the user node instead of root (#6365) (f636616)
  • core Drop debian and rhel7 images (#6365) (f636616)
  • core Drop support for deprecated WEBHOOK_TUNNEL_URL env variable (#6363)
  • core Execution mode defaults to main now, instead of own (#6363)
  • core Default push backend is websocket now, instead of sse (#6363)
  • core Stop loading custom/community nodes from n8n's node_modules folder (#6396) (a45a2c8)
  • core User management is mandatory now. basic-auth, external-jwt-auth, and no-auth options are removed (#6362) (8c008f5)
  • core Allow syntax errors and expression errors to fail executions (#6352) (1197811)
  • core Drop support for request library and N8N_USE_DEPRECATED_REQUEST_LIB env variable (#6413) (632ea27)
  • core Make date extensions outputs match inputs (#6435) (85372aa)
  • core Drop support for executeSingle method on nodes (#4853) (9194d8b)
  • core Change data processing for multi-input-nodes (#4238) (b8458a5)

From github.com/n8n-io/n8n/blob/master/CHANGELOG.md

Full release notes for 1.0.0

1.0.1 – 1.1.1: no action items (7 versions)

1.2.0 2023-08-09

Breaking

What changed?

For the Linear node, priority in issue creation is 4 (previously incorrectly 3) for Low.

When is action necessary?

If you were using Low, you were setting a priority of Normal, so please double check you are setting the priority you intend.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.2.0

1.2.1 – 1.4.1: no action items (6 versions)

1.5.0 2023-08-31

Breaking

What changed?

In the Code node, console.log does not output to stdout by default.

When is action necessary?

If you were relying on console.log for non-manual executions of a Code node, you need to set the env variable CODE_ENABLE_STDOUT to true to send Code node logs to process's stdout.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.5.0

1.5.1: no action items (1 version)

1.6.0 2023-09-06

Breaking

What changed?

The env var N8N_PERSISTED_BINARY_DATA_TTL no longer has any effect and can be removed. This legacy flag was originally introduced to support ephemeral executions (see details), which are no longer supported.

When is action necessary?

If using this flag, remove it from your settings.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.6.0

1.6.1 – 1.8.2: no action items (6 versions)

1.9.0 2023-09-28

Breaking

What changed?

In nodes, this.helpers.getBinaryStream() is now async.

When is action necessary?

If your node uses this.helpers.getBinaryStream(), add await when calling it.

Example:

What changed?

The env vars N8N_BINARY_DATA_TTL and EXECUTIONS_DATA_PRUNE_TIMEOUT no longer have any effect and can be safely removed. Instead of relying on a TTL system for binary data, n8n currently cleans up binary data together with executions during pruning.

When is action necessary?

If using these flags, remove them from your settings and be mindful of the new behavior.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.9.0

1.9.1 – 1.21.1: no action items (26 versions; 7 backports, released after the next line began, are not on this route)

1.22.0 2023-12-21

Breaking

What changed?

Hash algorithm ripemd160 is dropped from .hash() expressions. sha3 hash algorithm now returns a valid sha3-512 has, unlike the previous implementation that returned a Keccak hash instead.

When is action necessary?

If you are using .hash helpers in expressions with hash algorithm ripemd160, you need to switch to one of the other supported algorithms.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.22.0

1.22.1 – 1.23.0: no action items (5 versions; 1.22.5 – 1.22.6, released after 1.23.0, are not on this route)

1.24.0 2024-01-10

Breaking

What changed?

The flag N8N_CACHE_ENABLED was removed. The cache is now always enabled.

Additionally, expressions in credentials now follow the paired item, so if you have multiple input items, n8n will try to pair the matching row to fill in the credential details.

In the Monday.com Node, due to API changes, the data structure of entries in column_values array has changed

When is action necessary?

If you are using the flag N8N_CACHE_ENABLED, remove it from your settings.

In regards to credentials, if you use expression in credentials, you might want to revisit them. Previously, n8n would stick to the first item only, but now it will try to match the proper paired item.

If you are using the Monday.com node and refering to column_values property, check in table below if you are using any of the affected properties of its entries.

ResourceOperationPreviousNew
BoardGetownerowners
BoardGet Allownerowners
Board ItemGettitlecolumn.title
Board ItemGet Alltitlecolumn.title
Board ItemGet By Column Valuetitlecolumn.title
Board ItemGetadditional_infocolumn.settings_str
Board ItemGet Alladditional_infocolumn.settings_str
Board ItemGet By Column Valueadditional_infocolumn.settings_str

*column.settings_str is not a complete equivalent additional_info

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.24.0

1.24.1: no action items (1 version)

1.25.0 2024-01-17

Breaking

What changed?

If the N8N_ENCRYPTION_KEY environment variable on a main instance does not match the encryptionKey in the config file, the main instance will not initialize. If the N8N_ENCRYPTION_KEY environment variable is missing on a worker, the worker will not initialize.

When is action necessary?

If passing an N8N_ENCRYPTION_KEY environment variable to the main instance, make sure it matches the encryptionKey in the config file. If you are using workers, pass the N8N_ENCRYPTION_KEY environment variable to them.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.25.0

1.25.1 – 1.26.0: no action items (2 versions)

1.27.0 2024-01-31

Breaking

What changed?

The execution mode own was removed. If EXECUTIONS_PROCESS is set to main or if executions.process in a config file is set to main n8n will print a warning, but start up normally. If EXECUTIONS_PROCESS is set to own or if executions.process in a config file is set to own n8n will print an error message and refuse to start up.

When is action necessary?

If you use own mode and need the isolation and performance gains, please consider using queue mode instead, otherwise switch to main mode by removing the environment variable or config field. If you have the environment variable EXECUTIONS_PROCESS or the config field executions.process set, please remove them. The environment variable has no effect anymore and the configuration field will be removed in future releases, prevent n8n from starting if it is still set.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Breaking

From github.com/n8n-io/n8n/blob/master/CHANGELOG.md

Full release notes for 1.27.0

1.27.1 – 1.31.1: no action items (9 versions; 1.27.3, released after 1.28.0, is not on this route)

1.31.2: released after 1.32.0; not on this route

1.32.0 2024-03-06

Breaking

What changed?

n8n auth cookie has Secure flag set by default now.

When is action necessary?

If you are running n8n without HTTPS on a domain other than localhost, you need to either setup HTTPS, or you can disable the secure flag by setting the env variable N8N_SECURE_COOKIE to false.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.32.0

1.32.1 – 1.36.1: no action items (9 versions; 1.32.2, released after 1.33.0, is not on this route)

1.36.2 – 1.36.4: released after 1.37.0; not on this route

1.37.0 2024-04-10

Breaking

What changed?

The --file flag for the execute CLI command has been removed.

When is action necessary?

If you have scripts relying on the --file flag for the execute CLI command, update them to first import the workflow and then execute it using the --id flag.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.37.0

1.37.1 – 1.39.1: no action items (6 versions; 3 backports, released after the next line began, are not on this route)

1.40.0 2024-05-02

Breaking

What changed?

The default value for the DB_POSTGRESDB_USER environment variable was switched from root to postgres.

When is action necessary?

If your Postgres connection is relying on the old default value root for the DB_POSTGRESDB_USER environment variable, you must now explicitly set DB_POSTGRESDB_USER to root in your environment.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.40.0

1.41.0 – 1.46.0: no action items (10 versions; 4 backports, released after the next line began, are not on this route)

1.47.0 2024-06-20

Breaking

What changed?

Calling $(...).last() (or $(...).first() or $(...).all() respectively) without arguments is returning the the last item (or first or all items) of the output that connects the two nodes. Before it was returning the item/items of the first output of that node.

When is action necessary?

If you are using $(...).last() (or $(...).first() or $(...)all() respectively) without arguments for nodes that have multiple outputs (e.g. If, Switch, Compare Datasets, etc.) and you want it to default to the first output. In that case change it to $(...).last(0) (or first or all respectively).

This does not affect the Array functions [].last(), [].first().

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.47.0

1.47.1 – 1.51.1: no action items (10 versions; 3 backports, released after the next line began, are not on this route)

1.51.2: released after 1.52.0; not on this route

1.52.0 2024-07-24

Breaking

What changed?

Prometheus metrics enabled via N8N_METRICS_INCLUDE_DEFAULT_METRICS and N8N_METRICS_INCLUDE_API_ENDPOINTS were fixed to include the default n8n_ prefix.

When is action necessary?

If you are using Prometheus metrics from these categories and are using a non-empty prefix, please update those metrics to match their new prefixed names.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.52.0

1.52.1 – 1.54.2: no action items (7 versions; 1.53.2, released after 1.54.0, is not on this route)

1.54.3 – 1.54.4: released after 1.55.0; not on this route

1.55.0 2024-08-14

Breaking

What changed?

The N8N_BLOCK_FILE_ACCESS_TO_N8N_FILES environment variable now also blocks access to n8n's static cache directory at ~/.cache/n8n/public.

When is action necessary?

If you are writing to or reading from a file at n8n's static cache directory via a node, e.g. Read/Write Files from Disk, please update your node to use a different path.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.55.0

1.55.1 – 1.56.2: no action items (6 versions)

1.57.0 2024-08-28

Breaking

What changed?

The verbose log level was merged into the debug log level.

When is action necessary?

If you are setting the env var N8N_LOG_LEVEL=verbose, please update your log level to N8N_LOG_LEVEL=debug.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.57.0

1.58.0 – 1.62.3: no action items (13 versions; 2 backports, released after the next line began, are not on this route)

1.62.4 – 1.62.6: released after 1.63.0; not on this route

1.63.0 2024-10-09

Breaking

What changed?

  1. The worker server used to bind to IPv6 by default. It now binds to IPv4 by default.
  2. The worker server's /healthz used to report healthy status based on database and Redis checks. It now reports healthy status regardless of database and Redis status, and the database and Redis checks are part of /healthz/readiness.

When is action necessary?

  1. If you experience a port conflict error when starting a worker server using its default port, set a different port for the worker server with QUEUE_HEALTH_CHECK_PORT.
  2. If you are relying on database and Redis checks for worker health status, switch to checking /healthz/readiness instead of /healthz.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.63.0

1.63.1 – 1.64.2: no action items (7 versions)

1.64.3: released after 1.65.0; not on this route

1.65.0 2024-10-24

Breaking

What changed?

Queue polling via the env var QUEUE_RECOVERY_INTERVAL has been removed.

When is action necessary?

If you have set the env var QUEUE_RECOVERY_INTERVAL, so you can remove it as it no longer has any effect.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.65.0

1.65.1 – 1.81.2: no action items (40 versions; 18 backports, released after the next line began, are not on this route)

1.81.3 2025-03-03

Breaking

What changed?

The Form nodes no longer allows input field types for custom HTML to prevent malicious javascript from being added.

When is action necessary?

If you were previously using input in the custom HTML for a Form node.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.81.3

1.81.4 – 1.82.0: no action items (2 versions)

1.82.1 2025-03-04

Breaking

Same text as in 1.81.3, above.

Full release notes for 1.82.1

1.82.2: no action items (1 version)

1.82.3 – 1.82.4: released after 1.83.0; not on this route

1.83.0 2025-03-12

Breaking

Same text as in 1.81.3, above.

Full release notes for 1.83.0

1.83.1 – 1.97.1: no action items (34 versions; 7 backports, released after the next line began, are not on this route)

1.98.0 2025-06-11

Breaking

What changed?

The last_activity metric included as a part of route metrics has been changed to output a Unix time in seconds from the previous timestamp label approach. The labeling approach could result in high cardinality within Prometheus and thus result in poorer performance.

Stricter parameters for iframe, video, and source tags when using the Form node.

When is action necessary?

If you've been ingesting route metrics from your n8n instance (version 1.81.0 and newer), you should analyze how the last_activity metric has affected your Prometheus instance and potentially clean up the old data. Future metrics will also be served in a different format, which needs to be taken into account.

If you are using iframe, video, or source tags with attributes beyond those listed here or are using schemes which are neither http or https, you will need to update your node or workflow.

What changed?

The minimum Node.js version required for n8n is now v20.

When is action necessary?

If you're using n8n via npm or PM2 or if you're contributing to n8n.

How to upgrade:

Update the Node.js version to v20 or above.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.98.0

1.98.1 – 1.101.1: no action items (8 versions; 1.98.2, released after 1.99.0, is not on this route)

1.101.2 – 1.101.3: released after 1.102.0; not on this route

1.102.0 2025-07-07

Breaking

What changed?

The N8N_RUNNERS_ALLOW_PROTOTYPE_MUTATION flag has been replaced with N8N_RUNNERS_INSECURE_MODE. The new flag disables all task runner security measures and is intended as an escape hatch for users who value compatibility with libraries like puppeteer at the cost of security.

When is action necessary?

If you are using the N8N_RUNNERS_ALLOW_PROTOTYPE_MUTATION flag, or if you find that the task runner does not currently support an external module that you rely on, then consider setting N8N_RUNNERS_INSECURE_MODE=true, at your own risk.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.102.0

1.102.1 – 1.102.3: no action items (3 versions)

1.102.4: released after 1.103.0; not on this route

1.103.0 2025-07-14

Breaking

What changed?

We will no longer be allowing users to use responseData within the Webhook node since this is now sandboxed in an iframe, which may break workflows relying on browser APIs like localStorage and fetch from within custom code.

When is action necessary?

If your workflow is using the Webhook node and uses JavaScript in responseData to make fetch calls or access localStorage, you may need to refactor it due to the new iframe sandboxing.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.103.0

1.103.1 – 1.106.3: no action items (10 versions; 4 backports, released after the next line began, are not on this route)

1.107.0 2025-08-11

Breaking

What changed?

The CLI flag --reinstallMissingPackages, deprecated a year ago in version 1.154.0, has been removed.

When is action necessary?

If you are using this flag, please switch to the environment variable N8N_REINSTALL_MISSING_PACKAGES.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.107.0

1.107.1 – 1.108.1: no action items (5 versions; 1.107.4, released after 1.108.0, is not on this route)

1.108.2: released after 1.109.0; not on this route

1.109.0 2025-08-25

Breaking

What changed?

Webhook HTML responses were sandboxed to an iframe starting from 1.103.1 due to security. The sandboxing mechanism is now changed to use Content-Security-Policy header instead of an iframe. The security guarantees stay the same, but the mechanism is less breaking.

When is action necessary?

If you have workflows that return HTML responses from Webhook Trigger node or Respond to Webhook node.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.109.0

1.109.1 – 1.112.3: no action items (8 versions; 3 backports, released after the next line began, are not on this route)

1.112.4 – 1.112.6: released after 1.113.0; not on this route

1.113.0 2025-09-22

Breaking

What changed?

Support for bare repositories in Git Node was dropped in the cloud version of n8n due to security reasons. Also, an environment variable N8N_GIT_NODE_DISABLE_BARE_REPOS was added that allows self-hosted users to disable bare repositories as well.

When is action necessary?

If you have workflows that use the Git Node and work with bare git repositories.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.113.0

1.113.1 – 1.121.2: no action items (27 versions; 7 backports, released after the next line began, are not on this route)

1.121.3: released after 1.122.0; not on this route

1.122.0 2025-11-24

Breaking

What changed?

The way to add third-party dependencies to the n8nio/runners image has changed. More details here.

When is action necessary?

If you are adding third-party dependencies to the n8nio/runners image using package.json and extras.txt and building the image yourself, please extend the image as instructed in the link above.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 1.122.0

1.122.2 – 1.123.4: no action items (8 versions; 1.122.5, released after 1.123.0, is not on this route)

1.123.5 – 1.123.82: released after 2.0.0; not on this route

2.0.0 2025-12-08

Quoted from docs.n8n.io/changelog/v20-breaking-changes

Upgrade guide

Behavior changes

Return expected sub-workflow data when the sub-workflow resumes from waiting (waiting for webhook, forms, HITL, etc.)

Previously, when an execution (parent) called a sub-execution (child) that contained a node that causes the sub-execution to enter the waiting state and the parent-execution is set up to wait for the sub-execution's completion, the parent-execution would receive incorrect results.

Entering the waiting state would happen for example if the sub-execution contains a Wait node with a timeout higher than 65 seconds or a webhook call or a form submission, or a human-in-the-loop node, like the slack node.

Parent-Workflow: [image: Parent workflow with a Manual Trigger connected to an Execute Workflow node]

Sub-Workflow: [image: Sub-workflow triggered by Execute Workflow Trigger, running a Wait node followed by an Edit Fields node]

n8n 1.0: The parent-execution reproduces the sub-execution's input as its output.: [image: n8n 1.0: Parent execution won't receive the result of the child execution]

n8n 2.0: The parent execution receives the result of the child execution: [image: n8n 2.0: Parent execution will receive the result of the child execution]

This allows using human-in-the-loop nodes in the sub-workflow and use the results (for example approving or declining an action) in the parent-workflow.

Migration path: Review any workflows that call sub-workflows and expect to receive the input to the sub-workflow. Update these workflows to handle the new behavior, where the parent-workflow receives the output from the end of the child-workflow instead.

Start node removed

The Start node is no longer supported. This node was the original way to begin workflows but more specific trigger nodes now replace it.

Migration path: Replace the Start node based on how you use your workflow:

  • Manual executions: Replace the Start node with a Manual Trigger node.
  • Sub-workflows: If another workflow calls this workflow as a sub-workflow, replace the Start node with an Execute Workflow Trigger node and activate the workflow.
  • Disabled Start nodes: If the Start node is disabled, delete it from the workflow.

Saving and publishing workflows

The new workflow publishing system replaces the previous active/inactive toggle. This means that the old "Activate/Deactivate" toggles become the new "Publish/Unpublish" buttons. This change gives you better control over when your workflow changes go live, reducing the risk of accidentally deploying work-in-progress changes to production. More information can be found here: Saving and publishing workflows.

Removed nodes for retired services

The following nodes have been removed because the external services they connect to are no longer available:

  • Spontit node
  • crowd.dev node
  • Kitemaker node
  • Automizy node

Migration path: If your workflows use any of these nodes, update or remove those workflows to avoid errors.

Upgrade guide

Security

Block environment variable access from Code Node by default

To improve security, n8n will block access to environment variables from the Code node by default. The default value for N8N_BLOCK_ENV_ACCESS_IN_NODE is now set to true.

Migration path: If your workflows require access to environment variables in Code nodes, set N8N_BLOCK_ENV_ACCESS_IN_NODE=false in your environment configuration. For sensitive data, use credentials or other secure methods instead of environment variables.

Enforce settings file permissions

n8n will require strict file permissions for configuration files to improve security. By default, configuration files must use 0600 permissions, which means only the file owner can read and write them. This approach is similar to how SSH protects private keys.

Migration path: To test this behavior before n8n 2.0, set N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true. If your environment doesn't support file permissions (for example, on Windows), set N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false to disable this requirement.

Enable task runners by default

n8n will enable task runners by default to improve security and isolation. All Code node executions will run on task runners.

Migration path: Before upgrading to n8n 2.0, set N8N_RUNNERS_ENABLED=true to test this behavior. Make sure your infrastructure meets the requirements for running task runners. For additional security, consider using external mode.

$evaluateExpression no longer works in the Code node

Because Code node executions now run on task runners in secure mode by default, the $evaluateExpression() convenience method no longer works inside the Code node. Secure mode disables evaluating strings as code, which is the mechanism expressions rely on, so $evaluateExpression() calls in a Code node return null or error. Expressions in regular node fields, such as the Edit Fields (Set) node, aren't affected.

Migration path: Move the expression evaluation out of the Code node, in order of preference:

  • Write the logic directly in JavaScript instead of calling $evaluateExpression().
  • Evaluate the expression in an Edit Fields (Set) node before the Code node, then read the result from the incoming item.
  • If you have no other option, set N8N_RUNNERS_INSECURE_MODE=true to re-enable the disabled JavaScript features. This turns off the task runner's security measures and is discouraged for production use.

$evaluateExpression() in the Code node may be removed entirely in a future version, so treat N8N_RUNNERS_INSECURE_MODE=true as a temporary workaround rather than a permanent solution.

Remove task runner from n8nio/n8n docker image

Starting with n8n 2.0, the main n8nio/n8n Docker image will no longer include the task runner for external mode. You must use the separate n8nio/runners Docker image to run task runners in external mode.

Migration path: If you run task runners in Docker with external mode, update your setup to use the n8nio/runners image instead of n8nio/n8n.

Remove Pyodide-based Python Code node and tool

n8n will remove the Pyodide-based Python Code node and tool and replace them with a task runner-based implementation that uses native Python for better security and performance. Starting in n8n 2.0, you can only use Python Code nodes with task runners in external mode and native Python tools.

The native Python Code node doesn't support built-in variables like _input or dot access notation, which were available in the Pyodide-based version. For details, see the Code node documentation.

The native Python tool supports _query for the input string that the AI Agent passes to the tool when it calls it.

Migration path: To continue using Python in Code nodes, set up task runners in external mode and review your existing Python Code nodes and tools for compatibility.

Disable ExecuteCommand and LocalFileTrigger nodes by default

n8n will disable the ExecuteCommand and LocalFileTrigger nodes by default because they pose security risks. These nodes allow users to run arbitrary commands and access the file system.

Migration path: If you need to use these nodes, remove them from the disabled nodes list in your n8n configuration by updating the NODES_EXCLUDE environment variable. For example, set NODES_EXCLUDE="[]" to enable all nodes, or remove only the specific nodes you need.

Require authentication on OAuth callback URLs by default

n8n will require authentication for OAuth callback endpoints by default. The default value for N8N_SKIP_AUTH_ON_OAUTH_CALLBACK will change from true (no authentication required) to false (authentication required).

Migration path: Before upgrading to n8n 2.0, set N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false and test your OAuth integrations to ensure they work with authentication enabled.

Set default value for N8N_RESTRICT_FILE_ACCESS_TO

n8n will set a default value for N8N_RESTRICT_FILE_ACCESS_TO to control where file operations can occur. This affects the ReadWriteFile and ReadBinaryFiles nodes. By default, these nodes can only access files in the ~/.n8n-files directory.

Migration path: Review your workflows that use file nodes and make sure they only access files in the allowed directory. If you need to allow access to other directories, set the N8N_RESTRICT_FILE_ACCESS_TO environment variable to your desired path.

Change the default value of N8N_GIT_NODE_DISABLE_BARE_REPOS to true

By default, the Git node will now block bare repositories for security reasons. The default value for N8N_GIT_NODE_DISABLE_BARE_REPOS is set to true, which means bare repositories are disabled unless you change this setting.

Migration path: If your workflows need to use bare repositories, set N8N_GIT_NODE_DISABLE_BARE_REPOS=false in your environment configuration to enable them.

Upgrade guide

Data

Drop MySQL/MariaDB support

n8n will no longer support MySQL and MariaDB as storage backends. This support was deprecated from n8n 1.0. For best compatibility and long-term support, use PostgreSQL. MySQL node will continue to be supported as before.

Migration path: Before upgrading to n8n 2.0, use the database migration tool to move your data from MySQL or MariaDB to PostgreSQL or SQLite.

Remove SQLite legacy driver

n8n will remove the legacy SQLite driver due to reliability issues. The pooling driver will become the default and only SQLite driver. The pooling driver uses WAL mode, a single write connection, and a pool of read connections. Our benchmarks show it can be up to 10 times faster.

Migration path: The sqlite-pooled driver will become the default automatically. You can enable pooling now by setting DB_SQLITE_POOL_SIZE to a value greater than 0. The default pool size will be set to 2.

Remove in-memory binary data mode

n8n will remove the default mode for N8N_DEFAULT_BINARY_DATA_MODE, which keeps execution binary data in memory during execution. For better performance and stability the following options will be available starting from n8n 2.0:

  • filesystem: Binary data is stored in the filesystem. Default option in regular mode.
  • database: Binary data is stored in the database. Default option in queue mode.
  • s3: Binary data is stored in S3 compatible store.

The N8N_AVAILABLE_BINARY_DATA_MODES setting will also be removed, so the mode is now determined only by N8N_DEFAULT_BINARY_DATA_MODE.

Migration path: Filesystem or database mode will be used automatically based on configuration. Make sure your n8n instance has enough disk space to store binary data. For details, see the binary data configuration.

Upgrade guide

Configuration & Environment

Upgrade dotenv

n8n loads environment configuration from a .env file using the dotenv library. The library will be upgraded from version 8.6.0 to the latest version, which may change how .env files are parsed. Key breaking changes include:

  • Backtick support (#615): If your values contain backticks, wrap them in single or double quotes.
  • Multiline support: You can now use multiline values.
  • # marks the beginning of a comment: Lines starting with # are treated as comments.

Migration path: Review the dotenv changelog and update your .env file to ensure compatibility with the new version.

Remove n8n --tunnel option

The n8n --tunnel command-line option will be removed from n8n 2.0.

Migration path: If you currently use the --tunnel option for development or testing, switch to an alternative tunneling solution such as ngrok, localtunnel, or Cloudflare Tunnel. Update your workflow and documentation to reflect this change.

Remove QUEUE_WORKER_MAX_STALLED_COUNT

The QUEUE_WORKER_MAX_STALLED_COUNT environment variable and the Bull retry mechanism for stalled jobs will be removed because they often caused confusion and didn't work reliably.

Migration path: Delete this environment variable from your configuration. After upgrading, n8n will no longer automatically retry stalled jobs. If you need to handle stalled jobs, consider implementing your own retry logic or monitoring.

Remove N8N_CONFIG_FILES

The N8N_CONFIG_FILES environment variable has been removed.

Migration path: Delete this environment variable from your configuration. Move configuration into environment variables, an .env file or _FILE based configuration.

Upgrade guide

CLI & Workflow

Replace CLI command update:workflow

The update:workflow CLI command will be deprecated and replaced by two new commands to deliver similar functionality and more clarity:

  • publish:workflow with parameters id and versionId (optional)
  • The --all parameter will be removed to prevent accidental publishing of workflows in production environments
  • unpublish:workflow with parameters id and all

Migration path: Use the new publish:workflow command to publish workflows individually by ID, optionally specifying a version. For unpublishing, use the new unpublish:workflow command. This provides better clarity and control over workflow publishing states.

Upgrade guide

External Hooks

Deprecated frontend workflow hooks

The hooks workflow.activeChange and workflow.activeChangeCurrent will be deprecated. These will be replaced by a new hook workflow.published. The new hook will be triggered when any version of a workflow is published.

Migration path: Update your code to use the new workflow.published hook instead of workflow.activeChange and workflow.activeChangeCurrent. This hook provides more consistent behavior and will be triggered whenever a workflow version is published.

Upgrade guide

Release channels

n8n has renamed the release channels from latest and next to stable and beta, respectively.

The stable tag designates the latest stable release, and the beta tag designates the latest experimental release. These tags are available on both npm and Docker Hub. For now, n8n will continue to tag releases as latest and next. These tags will be removed in a future major version.

Recommendation: Pin your n8n version to a specific version number, for example, 2.0.0.

Breaking

What changed?

The npm command is no longer available in the n8nio/runners image. Only pnpm is available for package management.

When is action necessary?

If you are extending the n8nio/runners image and using npm to install dependencies. Replace any npm install commands with pnpm install in your Dockerfile or scripts.

From github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md

Full release notes for 2.0.0

2.0.1 – 2.42.0: no action items (178 versions; 107 backports, released after the next line began, are not on this route)

Release notes from github.com/n8n-io/n8n/releases, and packages/cli/BREAKING-CHANGES.md, and CHANGELOG.md, and n8n 2.0 breaking changes, checked 37 minutes ago. Only text the vendor marks as breaking, or puts in a warning/caution/important note, is shown; read the full notes for anything else. n8n keeps its breaking changes in packages/cli/BREAKING-CHANGES.md, one section per version (“What changed?”, “When is action necessary?”); each section is quoted whole as “Breaking” on its version. The “BREAKING CHANGES” sections of CHANGELOG.md (0.198.0, 1.0.0, 1.27.0) are quoted too, and each section of the docs page “n8n 2.0 breaking changes” is quoted as “Upgrade guide” on 2.0.0. GitHub release notes are commit lists and are not quoted. Versions come from npm (package n8n). No required stop is recorded: neither file nor the 2.0 page names a version to install first.