n8n 3.0 Upgrade Checklist for Community Node Makers

n8n 3.0 changes four things for community node makers. defaults.color is gone. n8n-node dev now runs n8n in a Docker or Podman container. Your local test workflows move to a new container volume. And self-hosted instances stop loading unverified community nodes by default. The other n8n-node commands don't change: n8n-node build, n8n-node lint, n8n-node release and npm create @n8n/node work as before (n8n's v3.0 breaking changes). Most nodes need a small code change and a new dev setup. The bigger risk is the last item, because it decides whether your users can still run your node after they upgrade.

When this matters

n8n released 3.0.0 as a beta on October 27, 2026, and plans the stable 3.x release for early December (n8n's 3.0 announcement). n8n's docs call the current 3.0.0 an "early access release". On n8n Cloud it appears as 3.0.0 Beta (early access) in the version picker.

Some dates and rules to plan around, all from n8n's announcement:

• The upgrade is one way. You can't roll back from 3.x to 2.x. The only way back is to restore a full backup.
• After the stable release, 2.x gets security and critical bug fixes for 12 months. New features ship on 3.x only.
• There's no direct path from 1.x to 3.x, and 1.x support ends on December 31, 2026.

Your users will move to 3.0 at different times over that year, so plan for your node to work on both 2.x and 3.x.

The checklist

• Remove defaults.color from every node description
• Replace any Font Awesome icon (fa:) with an SVG or PNG file icon
• Export the test workflows you want to keep before you update @n8n/node-cli
• Install Docker or Podman, or switch your dev loop to --external-n8n
• Add --external-n8n anywhere you pass --custom-user-folder
• Test the node on both a 2.x image and a 3.0 image with --n8n-image
• Decide what unverified users will do: submit for verification, or document the admin setting
• Update your README's install and development instructions

Each item is explained below.

1. Remove defaults.color and use a file icon

n8n 3.0 removes the deprecated defaults.color property from the node description type. It only ever tinted Font Awesome icons (icon: 'fa:...'). n8n's standard parameters reference says it has been deprecated since n8n 1.52.0.

What happens if you leave it in: the node keeps working, but a Font Awesome icon shows in a neutral color. Nodes with a file icon (icon: 'file:...') aren't affected.

The fix:

// Before
description: INodeTypeDescription = {
  displayName: 'Acme CRM',
  name: 'acmeCrm',
  icon: 'fa:address-book',
  defaults: {
    name: 'Acme CRM',
    color: '#1A82e2',
  },
  // ...
};

// After
description: INodeTypeDescription = {
  displayName: 'Acme CRM',
  name: 'acmeCrm',
  icon: { light: 'file:acmeCrm.svg', dark: 'file:acmeCrm.dark.svg' },
  defaults: {
    name: 'Acme CRM',
  },
  // ...
};

n8n's reference tells you not to reference Font Awesome and to embed an image file instead. SVG is recommended. A PNG should be 60x60 pixels. Keep the canvas square or close to square. A single icon: 'file:acmeCrm.svg' is also fine.

n8n's community-node ESLint plugin backs this up. Its icon-validation rule checks that icon files exist and use the file: prefix, and it's an error in the recommended config. A second rule, icon-prefer-themed-variants, warns when you ship one icon instead of light and dark variants. Run npm run lint after the change.

2. Set up Docker or Podman for n8n-node dev

The old n8n-node dev started n8n with npx n8n@latest. n8n 3.0 doesn't publish a runnable n8n package to npm, so the new CLI runs the official n8n image in a container. In practice, an old CLI can't test your node on 3.0 at all, because npm has no 3.0 to give it.

You have two options:

• Container (default). Install Docker or Podman, then run npm run dev as before. According to the CLI's README, it starts n8n at http://localhost:5678, mounts your project into the container's custom nodes folder, and pushes a reload when you save, including for icons and JSON files. CONTAINER_ENGINE=docker or CONTAINER_ENGINE=podman overrides the engine it detects. The README lists Colima, Rancher Desktop, OrbStack and a remote DOCKER_HOST as working too.
• Your own n8n. Run n8n-node dev --external-n8n, and start that instance with N8N_DEV_RELOAD=true. The README adds that the instance should use N8N_USER_FOLDER=~/.n8n-node-cli, the CLI's default folder, unless you point it elsewhere with --custom-user-folder. --n8n-url lets you point at a remote instance.

Check which CLI you have with npm list @n8n/node-cli. On November 3, 2026, the npm latest tag for @n8n/node-cli was still 0.54.6, and its README describes the old subprocess setup. The container-based CLI was published as 1.0.x under the rc tag. Recheck the tags before you pin a version in your project.

If you debug with breakpoints, attaching to a process inside a container needs a different setup. The simplest route is --external-n8n with an n8n you start yourself. See how to debug an n8n custom node in VS Code for the attach steps.

3. Export your test workflows first

With the new CLI, the workflows and credentials you make while testing live in a container volume named n8n-node-cli-data-<image>, not in ~/.n8n-node-cli/.n8n. n8n's docs say test data from earlier versions doesn't carry over. Export the test workflows you want to keep before you update the CLI or change images, then import them into the new instance.

Each image you test against gets its own volume, because n8n only migrates a database forward. Switching images gives you an empty instance, not a database an older version can't read. To list and reset volumes:

docker volume ls --filter name=n8n-node-cli-data
docker volume rm <volume>

With Podman, use the same commands with podman in place of docker.

4. Fix scripts that use --custom-user-folder

--custom-user-folder used to set where the CLI linked your node. It now names the N8N_USER_FOLDER of an instance you run yourself, and it has no effect in container mode. If your package.json scripts or CI pass it, add --external-n8n and start that instance with the same N8N_USER_FOLDER.

5. Test on 2.x and 3.0

Because 2.x stays supported for 12 months after the stable 3.x release, test the node against both. Pin an image per run:

n8n-node dev --n8n-image docker.n8n.io/n8nio/n8n:<n8n-version>

The CLI also reads N8N_NODE_DEV_IMAGE. Hot reload only works on images that serve POST /rest/dev/reload. Older tags still load your node, but you have to restart to pick up changes. Each image keeps its own test data (see step 3), so export the workflows you need into both.

6. Plan for unverified nodes being off

This is the change your users will notice first. In 3.0, N8N_UNVERIFIED_PACKAGES_ENABLED defaults to false instead of true. On an upgraded self-hosted instance, users can't install unverified community nodes from npm, and installed ones stop loading until an admin sets the variable back to true. n8n Cloud already offers verified community nodes only.

If your node isn't verified, you have two moves, and you can make both:

1. Submit it for verification now. n8n's submission docs say reviews can take up to four weeks.
2. Tell your users which setting to change. Put N8N_UNVERIFIED_PACKAGES_ENABLED=true in your README's self-hosted install section.

The full picture, including what happens to instances that install packages from environment variables, is in what n8n 3.0's unverified community node change means for node makers. If verification is new to you, why verified matters for a SaaS n8n integration explains the reach you lose without it.

7. Update your README

Three lines usually need to change:

• Install. Say whether the node is verified, and if it isn't, give the 3.0 admin setting.
• Develop. Say that npm run dev needs Docker or Podman from the 3.0 CLI on, or give the --external-n8n command.
• Compatibility. State which n8n versions you tested on, for example the 2.x and 3.0 images from step 5.

If your contributors followed the n8n-node starter setup, the npm run dev step there is the one that changes.

What doesn't change

• npm create @n8n/node still scaffolds the project.
• n8n-node build, n8n-node lint and n8n-node release are unchanged.
• The verification rules are the same: n8n-nodes- naming, no runtime dependencies, and a release from GitHub Actions with npm provenance. The n8n verified community node checklist lists each one.

Get it built and published under your own accounts

NativeShip turns your OpenAPI spec into official, branded integrations for n8n, Make, Zapier and Activepieces. For n8n, each build is checked with n8n's own tooling and pushed to your GitHub repo, then published to npm with provenance under your accounts, so the package stays yours. When your API changes, you rebuild from the spec instead of editing by hand. See how a node is generated from an OpenAPI spec. Approval is always n8n's decision, so we can't guarantee it.

Plans start at a one-time $149 (Developer) or $349 (Startup), or we can do it all for you. See pricing.