n8n Migration Report: the automatic checklist before upgrading to 2.0

Upgrading a piece of software that runs production workflows to a new major version is always a delicate moment: which node will behave differently, which environment variable will change its default value, which credential will suddenly get rejected? For the n8n 2.0 release, the team shipped a tool built specifically for this problem: the Migration Report, a built-in scanner that audits your instance before the upgrade and spells out exactly what's going to break. This guide covers what the tool checks, how to read its output, and how to use it to migrate without surprises.

Why n8n built a dedicated migration tool

n8n 2.0 introduces several default-behavior changes aimed at hardening self-hosted instances: Task Runners now systematically isolate Code node execution, the Execute Command and Local File Trigger nodes are disabled out of the box, and Code node access to environment variables is blocked by default. Each change is justified on its own, but stacked together they can silently break workflows that relied on the old behavior — often without a clear error message at the moment of the upgrade itself.

Rather than let every team discover these breakages after the fact, n8n built the Migration Report straight into the product, available since version 1.121.0 (well before 2.0 shipped), reachable by global admins under Settings > Migration Report.

What the report actually checks

The Migration Report scans an instance along two axes:

• Workflow-level issues: a specific node or behavior that will stop working as-is after the upgrade (for example, a workflow using Execute Command without the node having been explicitly re-enabled).
• Instance-level issues: environment variables or server configuration that need adjusting before migrating, independent of any single workflow.

Each finding is tagged with a severity level:

Severity	Meaning	Recommended action
Critical	The workflow will stop working after the upgrade	Fix before migrating
Medium	Behavior changes, worth reviewing for your context	Check before or right after migrating
Low	Minor change, no major functional impact	Can wait

The report also shows an overall compatibility summary: how many workflows will keep working with zero changes after the upgrade. Once fixes are made, hitting refresh recalculates that score — a clean report (zero critical items) is the signal that the instance is ready to upgrade.

The most common findings

In practice, three categories of issues come up most often:

1. Execute Command or Local File Trigger used without re-authorization. These nodes are disabled by default in 2.0 to shrink the attack surface; you need to explicitly remove them from the exclusion list via NODES_EXCLUDE in your environment variables if you genuinely need them.
2. A Code node depending on environment variables. A script that read process.env directly needs adjusting: the default block protects your credentials and secrets from an accidental leak through a poorly scoped Code node.
3. Task Runners-related behavior. Some very specific scripts (disk access, precise timing) can behave differently once they run inside the runner's isolated environment instead of the internal process — see our Task Runners guide for the available configuration variables.

A report that surfaces none of these three on an older instance is worth a manual double-check anyway: it usually means the instance makes little use of advanced self-hosted features, or it's running on n8n Cloud where these constraints don't apply the same way.

A checklist for a smooth migration

1. Back up the database before anything else — see our PostgreSQL backup and restore guide. The Migration Report lowers the risk, it doesn't remove it.
2. Open Settings > Migration Report and let the scan run on the current instance (before upgrading the version).
3. Fix critical items first: re-enable a needed node, adjust a Code script, tweak an environment variable.
4. Refresh the report to confirm no critical item remains, then work through medium-severity items as time allows.
5. Upgrade the instance, then run the Migration Report again afterward — the tool stays available in 2.0 and lets you confirm nothing was missed.
6. Manually test the workflows that matter most to your business (billing, customer notifications, syncs) before calling the migration done.

For an instance hosting sensitive workflows — GDPR audit trails, compliance automations close to what ships in the Compliance & Audit Pack (€149) — this pre-migration check isn't optional: a compliance automation that silently stops after an upgrade is exactly the kind of incident a regular audit is supposed to catch.

A bonus reason to migrate: fewer "Database Locked" errors

Fixing what the Migration Report flags isn't the only good reason to upgrade. n8n 2.0 also ships a new pooling driver for SQLite, which noticeably cuts down SQLITE_BUSY: database is locked errors — a classic pain point on self-hosted SQLite instances once several executions run in parallel (see our guide on migrating to PostgreSQL for the more radical fix). The underlying phenomenon has been documented in computer science for decades: a foundational study by Gray, Lorie, Putzolu and Traiger on lock granularity in shared databases (Granularity of Locks and Degrees of Consistency in a Shared Data Base, IBM Research, 1976) shows that lock contention rises sharply with the number of concurrent writes to the same data file — exactly the mechanism behind SQLite locking up when several n8n workflows write to the same database at once. Better pooling doesn't remove contention by nature, but it limits how many requests block each other at the same instant, with a direct effect on real-world stability.

Wrapping up

The Migration Report turns a major upgrade — always a legitimately nerve-wracking moment on a production instance — into an actionable checklist: what's going to break, why, and how to fix it beforehand instead of afterward. For any self-hosted instance running business-critical automations, whether that's FlowKit's packs or custom scripts, running Settings > Migration Report before a 2.0 upgrade takes a few minutes and saves hours of after-the-fact debugging.