Resolvendo o erro E2BIG e conexões recusadas

Q: O conflito de identidade: "node: command not found"?

Como estou utilizando o Bun pela sua velocidade de processamento, assumi que não precisaria do Node.js instalado. Contudo, ao rodar seeds do Prisma (bun prisma/seed.ts), o terminal retornou um erro informando que o comando node não existia.

Q: O "boss" final: E2BIG: Argument list too long?

Após resolver o banco e as dependências, tentei rodar bun run dev. Para minha surpresa, o terminal entrou em um loop de erro:

Resolvendo o erro E2BIG e conexões recusadas: uma jornada de debug no ecossistema Bun + next.js + prisma#

Recentemente, durante a migração de um ambiente de desenvolvimento para uma nova distro Linux (Mint), me deparei com uma sequência de erros que pareciam não ter conexão entre si, mas que revelaram muito sobre como os novos runtimes interagem com o sistema operacional.

Neste artigo, vou compartilhar como saí de um ECONNREFUSED no Prisma até o temido E2BIG: Argument list too long no Bun, e como resolvi cada um com métodos práticos e de baixo nível.

1. Pré-requisitos: verificação de versões e lockfiles#

Antes de iniciar o diagnóstico de qualquer anomalia no ambiente de desenvolvimento, certifique-se de que a cadeia de ferramentas de runtime e dependências locais estão em conformidade:

# Verificar versões dos componentes
node --version        # Node.js
bun --version         # Bun
npx prisma --version  # Prisma
psql --version        # PostgreSQL

# Garantir instalação íntegra e sem modificações no lockfile
bun install --frozen-lockfile

2. O primeiro obstáculo: `ECONNREFUSED` e o prisma client#

Ao subir a aplicação, o primeiro erro foi uma falha de conexão com o PostgreSQL. O Prisma disparava: Error [PrismaClientKnownRequestError]: code: 'ECONNREFUSED'.

Eu tinha o banco rodando, mas o Prisma simplesmente não o alcançava. Descobri que dois pontos são cruciais quando você muda de ambiente (ex: Windows/WSL para Linux nativo):

A. Status do serviço e porta do PostgreSQL#

No Linux, o serviço do PostgreSQL pode não estar configurado para iniciar automaticamente com o boot ou pode não estar aceitando conexões locais.

# Habilitar e iniciar o serviço do PostgreSQL imediatamente
sudo systemctl enable --now postgresql

# Validar se o PostgreSQL está aceitando conexões na porta padrão 5432
pg_isready -h 127.0.0.1 -p 5432

B. Resolução de DNS (localhost vs 127.0.0.1) e ipv6#

Muitas vezes, runtimes como o Node.js e o Bun resolvem o host localhost priorizando o endereço IPv6 (::1), enquanto a instância do PostgreSQL pode estar configurada para escutar unicamente em IPv4 (127.0.0.1).

Para diagnosticar o binding de portas do banco de dados:

# Verificar sockets IPv4 ativos na porta 5432
sudo ss -lntp | grep 5432

# Verificar sockets IPv6 ativos na porta 5432
sudo ss -lntp6 | grep 5432

# Inspecionar as definições de escuta no arquivo de configuração do PostgreSQL
sudo grep "listen_addresses" /etc/postgresql/*/main/postgresql.conf

Se o banco estiver escutando apenas em IPv4, evite usar localhost em sua URL de conexão. No .env, a string de conexão deve ser configurada explicitamente com o IP de loopback IPv4:

# Configuração recomendada (.env) para evitar problemas de tradução IPv6
DATABASE_URL="postgresql://user:[email protected]:5432/dbname?schema=public"

3. O conflito de identidade: "node: command not found"#

Como estou utilizando o Bun pela sua velocidade de processamento, assumi que não precisaria do Node.js instalado. Contudo, ao rodar seeds do Prisma (bun prisma/seed.ts), o terminal retornou um erro informando que o comando node não existia.

Por que isso ocorre?#

Muitos pacotes do ecossistema, incluindo geradores de binários do Prisma, invocam scripts de ciclo de vida (postinstall ou comandos em lote) que executam explicitamente o binário node no background.

Como resolver#

Use o NVM (Node Version Manager) para manter uma versão LTS estável instalada em paralelo ao Bun. Para validar a integridade e funcionamento do Bun no ecossistema:

# Validar localização física do binário do Bun
which bun

# Avaliar se o Bun consegue executar trechos de código em runtime
bun --eval "console.log('Bun está operacional')"

# Verificar se o Bun está lendo as variáveis do arquivo .env corretamente
bun --eval "console.log(process.env.DATABASE_URL)"

4. O "boss" final: `E2BIG: Argument list too long`#

Após resolver o banco e as dependências, tentei rodar bun run dev. Para minha surpresa, o terminal entrou em um loop de erro: error: Failed to run script dev due to error: E2BIG: Argument list too long (posix_spawn()).

O que causa o erro E2BIG?#

O erro E2BIG ocorre quando o tamanho total combinado dos argumentos e das variáveis de ambiente passados ao novo processo excede o limite ARG_MAX do kernel Linux (tipicamente 2 MB). Esse limite é consultado por getconf ARG_MAX e é completamente independente do limite de pilha de chamadas (ulimit -s).

No ecossistema de desenvolvimento moderno, o acúmulo de variáveis do arquivo .env, heranças do terminal (como NODE_OPTIONS ou PATH inflado por node_modules/.bin), e flags longas de build podem facilmente ultrapassar esse teto de posix_spawn.

flowchart LR A[process.env com muitas variáveis] --> B["env vars excedem 2MB"] C[NODE_OPTIONS com flags longas] --> B D[PATH enorme com node_modules/.bin] --> B B --> E[bun run dev executa posix_spawn] E --> F{"argv + envp excede ARG_MAX?"} F -->|Sim| G["ERRO E2BIG<br/>Argument list too long"] F -->|Não| H["Processo filho criado<br/>normalmente"] style G fill:#7f1d1d,stroke:#ef4444,color:#fff style H fill:#14532d,stroke:#22c55e,color:#fff style A fill:#1e3a5f,stroke:#3b82f6,color:#fff style B fill:#78350f,stroke:#eab308,color:#fff

5. Passo a passo da solução do E2BIG e alternativas#

Para resolver o erro de tamanho de argumentos, aplique as seguintes soluções:

A. Limpeza correta de cache e dependências#

Atenção: O comando bun pm cache clean não existe no Bun. A sintaxe correta para remover o cache de pacotes locais é a seguinte:

# Limpar cache do gerenciador de pacotes do Bun de forma correta
bun pm cache rm

# Alternativa: Remover o diretório de cache global do Bun manualmente
rm -rf ~/.bun/install/cache

# Limpar o cache de compilação do Next.js e da pasta node_modules
rm -rf .next
rm -rf node_modules/.cache

B. Identificar e remover processos zumbis#

Instâncias travadas ou órfãs do Bun/Node podem reter memória do shell ou locks de portas de processos anteriores:

# Encontrar processos em estado Zombie (Z) no sistema
ps aux | awk '{if ($8=="Z") print}'

# Listar processos ativos do Bun ou Node
ps aux | grep -E "bun|node" | grep -v grep

# Matar de forma forçada processos em execução
pkill -f "bun (run|dev|start)" 2>/dev/null || true
pkill -f "node (app|server|index|next)" 2>/dev/null || true
# Fallback de último recurso (encerra TODOS os processos bun/node no sistema - use com extrema cautela):
# killall -9 bun node

C. Diagnóstico e redução do tamanho do ambiente#

A solução correta para E2BIG é reduzir o payload de variáveis de ambiente, não alterar o stack size. Primeiro, meça e identifique o que está ocupando espaço:

# Medir o limite atual do sistema operacional
echo "ARG_MAX: $(getconf ARG_MAX) bytes"

# Medir o tamanho atual de todas as variáveis de ambiente
echo "Tamanho atual das env vars: $(printenv | wc -c) bytes"

# Calcular a margem restante antes de atingir o limite
echo "Espaço livre: $(( $(getconf ARG_MAX) - $(printenv | wc -c) )) bytes"

# Identificar as variáveis mais pesadas
printenv | awk -F= '{print length($0), $1}' | sort -rn | head -10

Com o diagnóstico feito, a solução mais eficaz é invocar o bun com um ambiente mínimo e controlado usando env -i:

# Solução definitiva: invocar bun com whitelist explícita de variáveis
env -i \
  HOME="$HOME" \
  PATH="$PATH" \
  DATABASE_URL="$DATABASE_URL" \
  NODE_ENV=development \
  bun run dev

Para limpar variáveis globais pesadas do shell atual antes de rodar:

unset NODE_OPTIONS
unset BUN_CONFIG_VERSION

D. Alternativas adicionais para redução do ambiente#

Higienizar o arquivo .env: Verifique se há linhas redundantes ou valores excessivamente longos:

   cat .env | wc -l
   wc -c .env

Encurtar o PATH: Remova entradas desnecessárias de node_modules/.bin acumuladas em sessões longas de shell.
Limitar flags de runtime: Se necessário, defina apenas a flag essencial:

   NODE_OPTIONS="--max-old-space-size=4096" bun run dev

6. Verificação do prisma e logs do sistema#

Sempre certifique-se de que o Prisma consegue ler o schema e se comunicar com o banco de dados antes de inicializar o servidor de renderização:

# Validar a sintaxe e integridade do arquivo prisma/schema.prisma
npx prisma validate

# Verificar se os binários do cliente do Prisma foram gerados corretamente
ls -la node_modules/.prisma/client/

# Sincronizar o schema com o banco de dados
# Prisma >= 5 (Agosto/2023 em diante): flag --preview-feature foi removido
npx prisma db push
# Prisma 4.x e anteriores: flag obrigatório
# npx prisma db push --preview-feature

Após corrigir o E2BIG, valide que o Bun consegue criar processos filhos e que o servidor responde:

# Verificar se o Bun consegue fazer spawn de processos corretamente
bun --eval "
  const { spawnSync } = require('child_process');
  const result = spawnSync('echo', ['test']);
  console.log('Spawn OK:', result.status);
"

# Iniciar o servidor e verificar se responde na porta 3000
bun run dev &
sleep 5 && curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Monitorando logs para debug avançado#

Se a conexão continuar falhando intermitentemente, monitore os logs de eventos do sistema e do banco de dados:

# Visualizar logs de erros de conexão do PostgreSQL
sudo tail -n 50 /var/log/postgresql/postgresql-*.log

# Buscar mensagens de falhas de autenticação no banco
sudo grep "authentication" /var/log/postgresql/postgresql-*.log | tail -n 20

# Verificar logs do kernel para rastrear se o Bun foi suspenso por falta de recursos
dmesg | tail -n 50

Checklist de troubleshooting: debug Bun + next.js + prisma#

Utilize este roteiro sequencial para solucionar problemas de conexão ou inicialização da stack:

1. Camada do banco de dados (PostgreSQL)#

[ ] O PostgreSQL está ativo? systemctl status postgresql
[ ] PostgreSQL inicia com o boot? systemctl is-enabled postgresql
[ ] PostgreSQL escuta na porta correta? ss -lntp | grep 5432
[ ] O banco de dados aceita conexões locais? pg_isready -h 127.0.0.1 -p 5432
[ ] A string do .env usa o IP numérico 127.0.0.1 em vez de localhost?

2. Compatibilidade do runtime e dependências#

[ ] Node.js está instalado em paralelo ao Bun (para compatibilidade)? node --version
[ ] Dependências foram instaladas sem mutação no lockfile? bun install --frozen-lockfile
[ ] O arquivo schema.prisma é sintaticamente válido? npx prisma validate

3. Diagnóstico de E2BIG e redução de ambiente#

[ ] Qual é o valor de ARG_MAX? getconf ARG_MAX
[ ] O payload atual de env vars está dentro do limite? printenv | wc -c
[ ] As variáveis mais pesadas foram identificadas? printenv | awk -F= '{print length($0), $1}' | sort -rn | head -10
[ ] O Bun foi invocado com ambiente mínimo via env -i?
[ ] O cache de pacotes locais do Bun foi limpo? bun pm cache rm
[ ] Pastas de cache e build temporárias (.next, node_modules/.cache) foram limpas?
[ ] Foram removidos processos órfãos ou zumbis do Bun e Node? pkill -f "bun (run|dev|start)" 2>/dev/null || true

Tabela de lacunas e impactos#

Omissão	Impacto
`ARG_MAX` vs `ulimit -s` confundidos	Solução proposta (`ulimit -s unlimited`) não resolve o problema e pode causar instabilidade
`env -i` como alternativa não mencionada	Leitor não aprende a técnica correta de isolamento de ambiente
`bun pm cache clean` vs `bun pm cache rm` explicado, mas sem fonte oficial	Pode mudar em versões futuras do Bun
`bun --bun` para forçar runtime Bun não mencionado	Se o script usar shebang `#!/usr/bin/env node`, o Bun delega ao Node e herda o ambiente completo
Versão do Prisma não especificada	Comandos com `--preview-feature` quebram silenciosamente no Prisma 5+
`* soft stack unlimited` aplicado globalmente no `/etc/security/limits.conf`	Pode causar falhas de `mmap` MAP_FAILED em processos multi-thread e esconder stack overflows

Considerações práticas#

A stack composta por Bun, Next.js e Prisma oferece alta produtividade, mas pode esbarrar em limites do sistema operacional e na resolução de DNS do loopback local. Ao configurar endpoints explicitados em formato IPv4 (127.0.0.1), manter o Node.js em coexistência com o Bun para compatibilidade de scripts, e reduzir o payload de variáveis de ambiente via env -i para resolver E2BIG, garantimos um ambiente resiliente e livre de travamentos no Linux.

Este artigo foi útil?

Deixe uma reação rápida para apoiar o conteúdo:

Este post está licenciado sob CC BY-NC.