Deploy falhou: como ler erros de build

Um build com falha costuma despejar um paredão de texto: avisos, stack traces, alertas de depreciação e uma linha final dizendo que o comando terminou com erro. Quase tudo é ruído. Uma linha, muitas vezes bem acima do fim, diz qual é o problema de verdade.

Achar essa linha é uma rotina curta, e os erros que ela revela em builds de Node.js e Python se repetem bastante. Cada um tem uma correção conhecida. Se "build" e "deploy" ainda parecem a mesma coisa, comece por o que é deploy.

Qual linha do log de build importa?#

Leia o log de cima para baixo, não de baixo para cima. As ferramentas de build param na primeira falha, mas continuam imprimindo: o gerenciador de pacotes avisa que um script falhou, depois que a instalação falhou, depois o código de saída. Essas últimas linhas descrevem a consequência, não a causa.

Use esta rotina:

1. Procure no log por error, ERR!, ERROR: ou FATAL.
2. Pegue a primeira ocorrência que não seja um aviso.
3. Leia as 5 a 10 linhas em volta dela. Os gerenciadores de pacotes imprimem ali mesmo os nomes e versões em conflito.
4. Copie a mensagem exata para a sua busca. O texto literal acha respostas mais rápido do que uma paráfrase.

Avisos (npm warn deprecated ...) raramente quebram um build. Trate-os como ruído até achar um erro real.

Por que o npm mostra ERESOLVE?#

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@1.0.0
npm error Found: react@19.0.0
npm error node_modules/react
npm error   react@"19.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from some-library@2.1.0

Um pacote declara uma peer dependency, ou seja, "o projeto que me usa precisa fornecer este pacote nesta faixa de versões". O seu projeto fornece outra versão, então o npm não consegue montar uma árvore consistente. Por padrão, o npm resolve alguns conflitos com a dependência não-peer mais próxima e imprime um aviso. Com strict-peer-deps ligado, ou quando o conflito não tem solução, vira falha.

Correções, da melhor para a pior:

• Atualize some-library para uma versão que suporte a sua.
• Faça downgrade ou fixe a versão do pacote que você controla, se não der para atualizar a biblioteca.
• Passe --legacy-peer-deps. O npm documenta que ela ignora as peerDependencies por completo, como faziam as versões 3 a 6 do npm. O build passa, mas a incompatibilidade continua lá.

Evite --force como correção. Segundo a documentação do npm, ela remove proteções contra efeitos colaterais indesejados, e o npm recomenda fortemente não usá-la se você não tiver clareza do que quer fazer.

Se você gerar o lockfile com --legacy-peer-deps, passe a mesma flag para o npm ci, senão a instalação provavelmente vai falhar.

Por que o npm ci falha quando o npm install funciona?#

npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: express@5.1.0 from lock file

O npm ci é o comando de instalação para builds automatizados. Ele exige um package-lock.json existente e, se o lockfile e o package.json não batem, sai com erro em vez de atualizar o lockfile. É de propósito: assim, todo build instala exatamente as versões que você testou.

A correção é local. Rode npm install, faça commit do package-lock.json alterado e faça o deploy de novo.

O que significa "Cannot find module" e por que só falha no servidor?#

Duas ferramentas diferentes imprimem textos parecidos.

Error: Cannot find module 'express'

Este é o Node.js carregando um módulo CommonJS. Com ES modules (import), o mesmo problema aparece como Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .... Nos dois casos, o pacote não está instalado, ou está em devDependencies enquanto o build faz uma instalação só de produção. Confira o package.json primeiro e depois confira se o caminho do import bate exatamente com o nome do arquivo, incluindo maiúsculas. Um arquivo Utils.js importado como ./utils funciona no Windows e no macOS, mas falha no Linux.

src/index.ts(3,20): error TS2307: Cannot find module './utils' or its corresponding type declarations.

Este é o compilador do TypeScript. Ou o arquivo não existe naquele caminho, ou o TypeScript não acha os tipos de um pacote. Instale o pacote @types/... correspondente ou confira o moduleResolution: a documentação do TypeScript diz que ele deve corresponder ao resolvedor do seu runtime ou bundler. Lembre que aliases de paths afetam a checagem de tipos, mas não o código gerado, então o código pode compilar e ainda assim falhar ao rodar.

Por que as versões diferem entre o seu computador e o build?#

Diferenças de versão causam muitas dessas falhas, porque o seu computador e o ambiente de build raramente rodam a mesma versão. Um recurso de sintaxe, um módulo nativo ou uma versão de pacote pode existir em um e não no outro.

Declare a versão que você testou. No Node.js, adicione o campo engines ao package.json:

{
  "engines": {
    "node": ">=22"
  }
}

Por padrão, o npm trata engines como recomendação e só avisa, e apenas quando o seu pacote é instalado como dependência. Ele não barra o seu próprio build, a menos que engine-strict esteja ligado. No Python, informe a versão do interpretador na documentação ou nas ferramentas do projeto e fixe os pacotes no requirements.txt.

O que significam os erros de build do pip?#

ERROR: Could not find a version that satisfies the requirement somepackage==9.9
ERROR: No matching distribution found for somepackage==9.9

A versão não existe, ou nenhum arquivo dela serve para a sua versão do Python e a sua plataforma. Confira o nome e a versão exatos no PyPI e veja se o pacote suporta a sua versão do Python.

ERROR: Cannot install package_a==1.0 and package_b==2.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    package_a 1.0 depends on package_c<3.0,>=2.4
    package_b 2.0 depends on package_c==2.3

Este é o ResolutionImpossible do pip. Leia o bloco "conflict is caused by": dois pacotes precisam de faixas incompatíveis de um terceiro. Afrouxe as suas próprias versões fixadas, remova pacotes que você não usa ou atualize um dos dois.

error: command 'gcc' failed: No such file or directory
ERROR: Failed building wheel for somepackage

Alguns pacotes não publicam wheel pronta para a sua plataforma, então o pip os compila a partir do código-fonte, o que exige um compilador e headers do sistema. Prefira uma versão que publique wheel. A opção --only-binary :all: faz o pip recusar builds a partir do código-fonte, então ele falha logo se não houver wheel.

E se o build ficar sem memória?#

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

O meio da mensagem varia conforme a situação (por exemplo Ineffective mark-compacts near heap limit), mas ela termina com JavaScript heap out of memory.

Ou o build simplesmente para com código de saída 137, que pela convenção do shell é 128 mais o sinal 9 (SIGKILL). Bundlers, TypeScript num projeto grande e processamento de imagens podem usar mais memória do que um container pequeno permite. O Node.js documenta o --max-old-space-size (em MiB) como o limite da seção de memória antiga do V8 e sugere cerca de 1536 numa máquina com 2 GiB, para sobrar espaço para outros usos:

NODE_OPTIONS=--max-old-space-size=1536 npm run build

Aumentar o limite só ajuda se a máquina tiver essa memória de verdade. Se não tiver, o sistema mata o processo, e aí vem o 137. Nesse caso, sobram duas saídas, mais RAM para o build ou menos trabalho por build: desligar source maps, dividir o projeto ou fazer o build localmente e enviar o resultado.

Como evitar que a mesma falha volte?#

• Faça o build como o servidor faz: apague o node_modules e rode npm ci, ou crie um ambiente virtual limpo e rode pip install -r requirements.txt.
• Faça commit dos lockfiles e fixe as versões de runtime.
• Confira a configuração cedo. Variáveis de ambiente ausentes falham tarde e de forma confusa, então leia o que são variáveis de ambiente.
• Rode o build no CI antes do deploy, como em deploy automático com GitHub Actions.
• Conheça o seu orçamento de memória. Como dimensionar RAM e CPU explica como estimar.

Como fazer isso na Square Cloud#

Na Square Cloud, a rotina de leitura é a mesma, mas o erro aparece em outro momento, porque não há etapa de build. No start, a plataforma instala as dependências (npm install quando não existe node_modules, sem as devDependencies, ou pip install -r requirements.txt no Python), e a saída dessa instalação aparece nos logs da aplicação. Se o projeto precisa ser compilado, rode o build num CI externo, como o GitHub Actions, e envie o resultado, ou coloque o build no comando de início.

Você faz o deploy por upload de ZIP, pela CLI, pelo GitHub ou pela extensão do VS Code. Os logs aparecem em tempo real no painel, na CLI e no VS Code, então dá para ler a primeira linha de erro assim que ela surge.

A memória é você quem define. Uma aplicação pode usar até 32 GB do pool de RAM compartilhado do plano, e você muda a quantidade nas configurações da aplicação ou pela API, o que ajuda se a aplicação estourar o heap enquanto roda. As variáveis de ambiente são definidas por aplicação, e uma mudança vale no próximo restart, sem rebuild. O agente Cubic no painel também pode ler os seus logs para ajudar a diagnosticar falhas, sempre a seu pedido.

Veja o que cada runtime suporta na página de runtimes.