---
name: v3-migration
description: >-
  Fix an existing workflow so it keeps working on n8n 3.0: replace removed nodes, rebuild removed AI Agent modes, rewrite removed expression helpers and review behavior changes flagged by the migration report. Load it when the user asks to migrate or update a workflow for n8n 3.0 or v3.
recommended_tools:
  - get_workflow_as_code
  - workflow_builder_build_workflow
  - get_node_types
  - run_workflow
  - ask_user
title: v3-migration
canonical_url: https://skilld.dev/gh/n8n-io/n8n/v3-migration
last_updated: 2026-11-12T10:06:17.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install n8n-io/n8n/v3-migration`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/v3-migration`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/n8n-io/n8n/v3-migration) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/v3-migration`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/v3-migration --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/v3-migration --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# n8n 3.0 Migration

The user wants an existing workflow to keep working on n8n 3.0. The instance
still runs 2.x, so the old nodes still load and run. The migration report lists
one finding per workflow and rule, and re-checks a workflow each time it is
saved, so a correct fix closes the finding by itself.

## Scope

- Fix the finding you were given, in the workflow you were given. Edit that
  workflow in place. Do not build a new workflow and do not touch other
  workflows, even when they have the same finding.
- Keep everything the finding does not need to change: other nodes,
  credentials, pinned data and connections.
- Do not publish on your own. If the workflow is published, the report shows
  the finding as fixed but not published until the fix is published, because
  the published version is the one that runs. Say so, and offer to publish the
  fixed version, following the publish rules in `workflow-builder`.

## Process

1. Load `workflow-builder` for the edit mechanics, and in the same turn read
   the workflow with `get_workflow_as_code` and the replacement node with
   `get_node_types`.
   Find each affected node from the finding by its name.
2. Decide whether the fix is mechanical or needs the user. It needs the user
   when the old behavior has no exact replacement, when the user's intent
   decides the right fix, or when you would have to guess a value. Then ask
   one focused question with `ask_user` before you edit.
3. Summarize in two or three sentences: what you changed, anything that
   behaves differently now, and anything the user still has to do (publish,
   test with real data, mark the finding as Won't fix in the report).

## Node replacements

A replacement node keeps the old node's name, because downstream expressions
reference nodes by name. It also takes over the old node's connections,
credentials and settings such as "Always Output Data", "Retry On Fail" and
"On Error".

### Function and Function Item to Code

Most Function code runs unchanged in the Code node. Change only what Code does
not provide, and keep the code's logic as it is: do not refactor or reformat
it.

- Function becomes Code with Mode "Run Once for All Items". Copy the code from
  the `functionCode` parameter. `items` and `$item()` still work in Code.
- Function Item becomes Code with Mode "Run Once for Each Item". In Code,
  `item` is the whole item `{ json, binary }`; in Function Item it was only the
  JSON. Replace each use of `item` with `item.json`, and return
  `{ json: <result>, binary: item.binary }`, because Function Item kept the
  input item's binary data.
- `getBinaryData()` / `setBinaryData()` and their async variants do not exist
  in Code. Read the item's `binary` property instead, and use
  `await this.helpers.getBinaryDataBuffer(itemIndex, propertyName)` when the
  code needs the file content.
- `getWorkflowStaticData(type)` becomes `$getWorkflowStaticData(type)`.

### HTTP Request Tool to HTTP Request

The old tool node used `{placeholder}` markers that the agent filled in, with
the placeholder definitions in a separate list. The replacement is the HTTP
Request node connected to the agent as a tool. Each placeholder becomes a
`$fromAI('<name>', '<description>', '<type>')` expression in the field that
used it. Keep the tool description, method, URL, authentication, headers and
query parameters, and use the old placeholder descriptions as the `$fromAI`
descriptions.

### Other replacements

- Interval to Schedule Trigger: recreate the interval with the same unit and
  value. Schedule Trigger does not support every interval (for example 90
  seconds); pick the closest supported one and tell the user.
- Read Binary File / Read Binary Files to Read/Write Files from Disk. The new
  node outputs file metadata as the item JSON instead of passing the input
  JSON through. If downstream nodes read the old input JSON, add a Merge or
  Edit Fields (Set) step to keep it.
- The old OpenAI node (`n8n-nodes-base.openAi`) to the new OpenAI node.
  Moderation maps to "Classify Text for Violations". Text edit and completion
  have no direct target: use a chat message with instructions, and ask the
  user when the intent is unclear.
- OpenAI Model to OpenAI Chat Model. The old default completion model does not
  exist on the chat endpoint; pick a current chat model and tell the user.
- Manual Chat Trigger to Chat Trigger with public access off. Below version
  1.1, chat runs passed the message as `input`; Chat Trigger passes
  `chatInput` and `sessionId`. Update downstream references such as
  `$json.input`.

### Removed nodes with no replacement

LangChain Code, Motorhead, Zep, Orbit and the GitHub Document Loader have no
direct replacement. Do not guess. Explain what the node did in this workflow
and ask the user to choose between the options that fit:

- LangChain Code: AI Agent or Basic LLM Chain with sub-nodes for custom chain
  or agent logic, an Embeddings sub-node for custom embeddings, the Evaluation
  node with Set Metrics for custom metrics, the Load mode of a Vector Store
  node for loading documents, and the Code node for plain data manipulation.
- Motorhead and Zep memory: another chat memory sub-node (for example
  Postgres, Redis or Simple Memory). Existing conversation history does not
  move.
- GitHub Document Loader: fetch the files with the GitHub node or HTTP
  Request, then load them with the Default Data Loader.

## AI Agent modes

Replace the node with an AI Agent on the latest version. Reconnect its chat
model, memory, tools and output parser, and carry over the system message and
prompt. For the SQL Agent mode, connect a database tool with the same
credential and move the old SQL prompt into the system message.

## $getPairedItem

Rewrite each `$getPairedItem(...)` call as `$('<node name>').item` for the
paired item of the current item, as `$('<node name>').itemMatching(index)`
inside a Code node, or as `$('<node name>').pairedItem(index)` where the call
passed an index.

## Behavior changes

These findings do not break the workflow, but its output changes. Explain the
change for this workflow and let the user decide. Do not change the workflow
only to clear the finding.

- "Always Output Data" on a node with several outputs: look at what follows
  the first output. If nothing there depends on the empty item, say so; the
  setting can stay, and the user can mark the finding as Won't fix. If a
  branch relies on it, propose turning the setting off and handling the empty
  case explicitly, and apply it after the user agrees. The finding stays open
  while the setting is on.
- Gmail Trigger below version 1.4: first ask whether the workflow relies on
  drafts, on sent mail, or on more than 10 emails per poll. If the user agrees,
  update the node to version 1.4 and keep its filters. For sent mail, propose a
  Schedule Trigger with Gmail "Get Many messages" and a search such as
  `in:sent`.
