O que muda no n8n 3.0

O n8n 3.0 encerra a instalação por npm e remove Nodes como Function e Item Lists. A versão também ativa a rotação da chave de criptografia por padrão. Este resumo segue os grupos da documentação oficial para você identificar as mudanças que afetam a sua instalação.

Onde a versão está

O n8n publicou a versão 3.0.0 como pre-release em 27 de outubro de 2026. O lançamento oficial está previsto para o início de dezembro. Depois dele, a linha 2.x recebe correções de segurança e de falhas críticas por 12 meses. Recursos novos saem só na 3.x.

A atualização para a 3.x não tem volta. Voltar para a 2.x exige restaurar o backup feito antes da atualização. Credenciais e histórico de execuções são mantidos.

Uma instalação na 1.x precisa passar pela 2.x antes. Não existe caminho direto da 1.x para a 3.x. O suporte à 1.x termina em 31 de dezembro de 2026.

A própria documentação recomenda começar pelo relatório de migração, disponível em Settings > Migration Report. Ele lista os workflows e as configurações da sua instância que precisam de atenção. O próximo tutorial da série mostra como ler esse relatório.

Instalação self-hosted só com Docker

O n8n 3.0 não roda mais com npm ou npx n8n. O projeto também não publica mais o pacote executável no npm. Se a sua instalação roda direto pelo Node.js, ela precisa passar para Docker antes da atualização.

Uma instalação que já roda com Docker Compose mantém o arquivo atual. Instalações em Kubernetes e Helm não são afetadas por essa mudança.

Nodes e helpers removidos

Workflows que usam um node removido falham na versão 3.0. Os casos mais comuns em instalações antigas são estes:

Node removido	Substituto indicado
Function	Code, no modo Run Once for All Items
Function Item	Code, no modo Run Once for Each Item
Item Lists	O node da operação usada: Split Out, Aggregate, Sort, Limit, Remove Duplicates ou Summarize
Cron e Interval	Schedule Trigger
HTML Extract	HTML, na operação Extract HTML Content
Read Binary File e Write Binary File	Read/Write Files from Disk
Read PDF	Extract from File, na operação Extract From PDF
Workflow Trigger	n8n Trigger

A lista oficial é maior e inclui nodes de IA, como a versão antiga do OpenAI e os nodes de vector store separados em inserção e leitura. Alguns não têm substituto direto, caso do LangChain Code e das memórias Motorhead e Zep.

Expressões que ainda chamam o helper $getPairedItem falham na execução do Node, pois ele foi removido. O caminho indicado é o item linking padrão, com $('<node-name>').item, itemMatching() ou pairedItem().

Comportamentos que mudam sem erro

Algumas mudanças não interrompem o workflow, mas alteram o resultado. Teste esses casos, porque a execução pode terminar com sucesso e entregar outra saída.

• Always Output Data em nodes com várias saídas. Em If e Switch, o item vazio só aparece quando todas as saídas estão vazias.
• Gmail Trigger anterior à versão 1.4. O node respeita o limite de e-mails por consulta e ignora rascunhos sem o filtro Include Drafts.
• Edit Image. As versões 1 e 1.1 saem. A versão 2 usa outra biblioteca de imagem, por isso desfoque, texto e redimensionamento podem mudar.

Segurança e configuração

Estas mudanças podem afetar as credenciais, o armazenamento de arquivos e a execução dos seus workflows. Confira os itens que se aplicam à sua instalação no ambiente de testes.

• Rotação da chave de criptografia

  A funcionalidade vem ativada por padrão e mantém legíveis as credenciais existentes. Você pode administrar a rotação em Settings > Data Encryption Keys, sem recriar as credenciais usadas pelos workflows.

  Confira: faça backup do banco antes da atualização, conforme a orientação do n8n para essa mudança.

• Signing secret do Slack

  O Slack Trigger usa o segredo da credencial Slack API para verificar as requisições recebidas. Se o campo estiver vazio, os workflows já publicados não são ativados após a atualização e param de receber eventos.

  Confira: copie o Signing Secret nas configurações do aplicativo Slack e preencha Signature Secret no n8n antes de migrar.

• Pasta de armazenamento

  No primeiro início, o n8n renomeia ~/.n8n/binaryData para ~/.n8n/storage. A instância não inicia se as duas pastas existirem.

  Confira: revise os volumes que apontam diretamente para binaryData e ajuste o caminho de montagem.

• Arquivos binários fora da memória

  O valor default de N8N_DEFAULT_BINARY_DATA_MODE não é aceito na v3. A atualização troca esse valor por filesystem.

  Confira: verifique o espaço no disco e a persistência do volume. Em queue mode, escolha um modo de armazenamento compatível com a sua instalação, pois filesystem não é suportado.

• Community Nodes não verificados

  Esses pacotes deixam de carregar por padrão, inclusive os já instalados.

  Confira: identifique os workflows afetados. Você pode substituir os pacotes por alternativas verificadas ou manter seu uso com N8N_UNVERIFIED_PACKAGES_ENABLED=true.

• Tempo limite do Code node

  O limite padrão cai de cinco minutos para um minuto, causando falha nas tarefas que ultrapassam esse tempo.

  Confira: teste os scripts mais demorados. Se a execução ultrapassar um minuto, ajuste N8N_RUNNERS_TASK_TIMEOUT, cujo valor é definido em segundos.

• Proteção contra SSRF

  Com a proteção contra SSRF (Server-Side Request Forgery) ativada e a lista default configurada, o n8n recusa chamadas a quatro novas faixas de IP.

  Confira: teste as chamadas aos seus serviços internos. Se uma chamada legítima falhar por essa proteção, configure o destino em N8N_SSRF_ALLOWED_IP_RANGES ou N8N_SSRF_ALLOWED_HOSTNAMES, preservando a lista default.

Recursos retirados

Confira quais funções saem da interface e o que você pode usar após a atualização.

• Chat Hub desativado por padrão

  O menu de chat desaparece na v3, mas sessões, agentes e mensagens permanecem no banco. A remoção completa está prevista para a v4.

  Confira: para continuar usando na v3, acrescente chat-hub a N8N_ENABLED_MODULES, preservando os módulos existentes separados por vírgula.

• Importação de workflow por URL

  A opção Import from URL sai do editor. Você ainda pode copiar e colar workflows ou importá-los por arquivo, CLI e API.

  Confira: baixe o JSON e use Import from File para importá-lo pelo editor.

• Permissão geral para segredos externos

  A opção Enable external secrets for project roles é retirada. No Enterprise, administradores e editores de projeto recebem acesso aos segredos externos por padrão.

  Confira: se você restringia esse acesso, configure papéis personalizados de projeto antes de atualizar.

• Aba Ask AI do Code node

  A aba Ask AI é removida do Code node. Os códigos gerados anteriormente permanecem nos workflows e continuam funcionando após a atualização.

  Confira: use a aba Code para escrever ou editar o código.

Como usar esta lista

Marque os grupos que aparecem no seu ambiente. Uma instalação por npm entra direto na etapa de preparação da infraestrutura. Workflows com nodes removidos entram na revisão de compatibilidade. Mudanças de comportamento entram na etapa de testes, porque só a comparação da saída mostra o efeito.