Erros comuns de deploy na Vertra Cloud e como corrigi-los

Este guia lista os erros mais frequentes ao fazer deploy na Vertra Cloud, no formato sintoma → causa → correção. Se sua aplicação não sobe, o motivo quase sempre é um destes: memória insuficiente (OOMKilled), uma dependência que falta no manifesto, um script de start ausente ou o servidor escutando em localhost em vez de 0.0.0.0.

Erros da plataforma

Os erros abaixo vêm da plataforma, não do seu código: memória, ciclo de vida do container, upload e limites do plano.

Aplicação não inicia / falhando

OOMKilled — Aplicação encerrada por falta de memória

Sintoma: A aplicação para sem nenhuma mensagem de erro, ou Killed aparece nos logs.Causa: A aplicação está usando mais RAM do que a alocada.Correção:

Aumente a memória alocada (experimente 50% a mais)
Java/JVM precisa de 512 MB+, aplicações com Puppeteer precisam de 512 MB+
Otimize o código para reduzir o uso de memória

Crash loop — reinício automático desativado

Sintoma: A aplicação caiu 5 vezes em 10 minutos e o reinício automático foi desativado por 24 horas.Causa: Um erro persistente no código (token inválido, dependência ausente, erro de sintaxe).Correção:

Verifique os logs para identificar o erro principal
Corrija o problema e faça um novo deploy
Erros de sintaxe e saída com código 0 NÃO disparam o reinício automático — a aplicação simplesmente para

A aplicação para logo em seguida (código de saída 0)

Sintoma: A aplicação inicia e para logo depois, sem erro.Causa: O processo não tem nada que o mantenha ativo (nenhum servidor HTTP, nenhum bot conectado, nenhum event loop).Correção:

Para bots: confirme que o cliente está fazendo login (client.login(token))
Para servidores: confirme que app.listen() está sendo chamado
Verifique se process.exit() não está sendo chamado por engano

Erros de deploy

ZIP grande demais (máximo de 100 MB)

Causa: Diretórios de dependências incluídos no ZIP (node_modules, venv, .git, etc).Correção: Exclua estes itens antes de gerar o ZIP:

JS/TS: node_modules, .npm, .next, dist
Python: venv, .venv, __pycache__, .cache
Go: vendor | Rust: target | .NET: bin, obj | Elixir: _build, deps | Java: target, .gradle, build

A instalação de dependências excede o limite de tempo (15 minutos)

Causa: Instalar as dependências leva tempo demais (muitos pacotes, compilação nativa). Erro: INSTALL_TIMEOUT.Correção:

Remova as dependências desnecessárias
Para aplicações Node.js grandes, considere rodar npm install localmente e incluir apenas o necessário

O comando de build falha ou excede o limite de tempo (10 minutos)

Causa: O build_command (o campo BUILD no vertracloud.config) terminou com erro (BUILD_FAILED) ou não terminou a tempo (BUILD_TIMEOUT). Ele roda depois da instalação das dependências e antes de a aplicação iniciar, em um ambiente com 2× a RAM da aplicação. Uma aplicação nova continua sendo criada, parada, com a saída do build nos seus logs.Correção:

Rode o comando localmente para ver o erro real
Simplifique o build ou aumente a memória da aplicação (o ambiente de build escala com ela)

Limite de deploys por hora atingido

Causa: Criar uma aplicação, enviar um ZIP, fazer deploy pelo GitHub, reinstalar dependências ou alterar o comando de build contam para um limite horário por conta (de 10 no Economy até 60 no Intermediary e em qualquer nível Enterprise). Erro: DEPLOY_RATE_LIMITED.Correção:

Aguarde o tempo indicado em details.retry_after
Reiniciar e parar a aplicação não contam para este limite

Estrutura de ZIP inválida

Causa: O ZIP tem uma pasta extra envolvendo os arquivos (por exemplo, my-project/src/index.js em vez de src/index.js).Correção: Os arquivos precisam estar na raiz do ZIP, não dentro de uma subpasta extra.

Erros de rede

O site retorna timeout / Connection refused

Causa: A aplicação está escutando em localhost ou 127.0.0.1 em vez de 0.0.0.0.Correção:

app.listen(80, '0.0.0.0')

app.listen(80, 'localhost')
app.listen(80, '127.0.0.1')

Sempre use 0.0.0.0 como host e a porta configurada em PORT.

Domínio personalizado não funciona

Causa: O DNS ainda não propagou, o CNAME está errado ou o plano não suporta o recurso.Correção:

Confirme que seu plano é Intermediary ou superior (domínios personalizados)
Verifique se o registro CNAME aponta para o endereço exibido em Registros DNS do domínio
Em um domínio raiz (example.com), seu provedor de DNS precisa suportar CNAME flattening
Um domínio que fique 14 dias sem DNS é removido automaticamente; depois disso, exclua os registros CNAME e TXT no seu provedor de DNS
A propagação do DNS pode levar até 48 horas
O SSL é provisionado automaticamente após a validação

Erros de banco de dados

Connection refused / SSL required

Causa: Conexão sem TLS, sem o certificado de cliente ou na porta padrão do motor.Correção:

Baixe os três arquivos de certificado na aba Certificados do banco de dados
Informe o certificado de cliente (.crt + .key) e use o .pem como CA — todos os motores exigem isso
Use a porta própria do banco de dados, mostrada na página dele — ela não é 5432, 27017, 6379 nem 3306
No MongoDB, adicione authSource=admin à URI
Veja Como me conecto a cada motor?

Conexões abertas demais

Causa: Cada conexão consome memória. Sem connection pooling, as conexões se acumulam.Correção:

Use connection pooling no cliente do seu banco de dados
Reduza o número de conexões simultâneas
Aumente a memória do banco de dados, se necessário

Proteções da plataforma

Aplicação pausada pelo Vertra Shield

Sintoma: Os botões de iniciar e reiniciar ficam desabilitados, com um banner “Pausado pelo Vertra Shield” e uma contagem regressiva no painel.Causa: O Vertra Shield parou a aplicação temporariamente depois de detectar tráfego acima dos limites. O painel mostra o motivo e o tempo restante da pausa, que pode chegar a 1 hora. O Shield apenas para a aplicação: ele nunca apaga a aplicação, seus arquivos ou seus dados.Correção:

Aguarde o tempo mostrado no painel antes de iniciar ou reiniciar a aplicação.
Revise o código: procure loops infinitos, chamadas recursivas sem limite ou requisições em massa sem controle.
Adicione rate limiting: implemente limites de requisições por IP ou por sessão no seu código.
Corrija a causa antes de a pausa terminar: iniciar, reiniciar, fazer deploy, alterar configurações e excluir a aplicação continuam bloqueados até lá, e ocorrências repetidas tornam a próxima pausa mais longa.

Node.js / JavaScript

Cannot find module 'xxx' / MODULE_NOT_FOUND

Causa: O módulo não está em dependencies no package.json, ou está só em devDependencies.Correção: Sem um comando de build, a plataforma instala apenas as dependencies; com um, ela também instala as devDependencies. Se o pacote for necessário em tempo de execução, mova-o para dependencies:

npm install discord.js --save

npm ERR! missing script: start

Causa: O package.json não tem um script start definido.Correção: Adicione ao package.json:

{
  "scripts": {
    "start": "node index.js"
  }
}

Ou defina o campo START no vertracloud.config.

SyntaxError: Cannot use import statement outside a module

Causa: Uso de import (ES Module) em um projeto CommonJS.Correção: Adicione ao package.json:

{
  "type": "module"
}

Ou converta para require().

ERR_REQUIRE_ESM — require() of ES Module not supported

Causa: Tentativa de usar require() em um pacote que só suporta ESM (por exemplo, node-fetch v3+, chalk v5+).Correção: Mude para ESM ("type": "module") ou use uma versão mais antiga do pacote (por exemplo, node-fetch@2).

ERESOLVE — unable to resolve dependency tree

Causa: Conflito de versões entre dependências (peer dependencies).Correção: Crie um arquivo .npmrc na raiz do projeto com:

legacy-peer-deps=true

Error: listen EADDRINUSE

Causa: A porta já está em uso, ou a aplicação tenta escutar duas vezes.Correção: Garanta que exista apenas um app.listen() no código. Use a variável de ambiente PORT.

Could not locate the bindings file (better-sqlite3)

Causa: Módulos nativos compilados no macOS/Windows não funcionam no container Linux.Correção: Não inclua node_modules/ no upload. A plataforma compila os módulos nativos para Linux automaticamente.

TypeScript

tsx / ts-node: command not found

Causa: O runtime do TypeScript não está nas dependencies.Correção: Adicione tsx ou ts-node às dependencies:

npm install tsx --save

TSError: Unable to compile TypeScript

Causa: Erros de compilação do TypeScript que não apareceram localmente, ou um tsconfig.json ausente.Correção: Inclua o tsconfig.json no upload. Corrija todos os erros de TS localmente antes do deploy. Considere pré-compilar e enviar o dist/.

Python

ModuleNotFoundError: No module named 'xxx'

Causa: O módulo não está no requirements.txt.Correção: Gere o arquivo com:

pip freeze > requirements.txt

Garanta que ele esteja na raiz do projeto.

requirements.txt não encontrado

Causa: O arquivo está faltando, tem o nome errado ou tem extensão dupla (.txt.txt — comum no Windows).Correção: Confira o nome exato do arquivo. No Windows, ative “mostrar extensões de arquivo” para verificar.

SyntaxError: invalid syntax

Causa: O código usa recursos de uma versão do Python mais nova que a selecionada (por exemplo, match/case do 3.10 no runtime 3.9).Correção: Selecione a versão correta do Python na configuração. Use VERSION=recommended para a versão estável mais recente.

UnicodeDecodeError / Erros de codificação

Causa: Arquivos com caracteres que não são UTF-8, ou o locale do container não está configurado.Correção: Salve todos os arquivos em UTF-8. Use encoding='utf-8' ao abrir arquivos:

with open('file.txt', 'r', encoding='utf-8') as f:
    ...

Flask/Django não acessível externamente

Causa: Uso do servidor de desenvolvimento, que escuta em 127.0.0.1.Correção: Use o Gunicorn em produção:

START=gunicorn app:app --bind 0.0.0.0:80

Nunca use o servidor de desenvolvimento do Flask/Django em produção.

Go

go.mod não encontrado / cannot find main module

Causa: O go.mod não está na raiz do projeto.Correção:

go mod init module-name
go mod tidy

Inclua o go.mod e o go.sum no upload.

Build falha / Binário incompatível

Causa: O binário foi compilado para macOS/Windows, não para Linux.Correção: Se estiver enviando o código-fonte, inclua go.mod e go.sum. Se estiver enviando um binário, compile-o para Linux:

GOOS=linux GOARCH=amd64 go build -o app main.go

Java

no main manifest attribute, in app.jar

Causa: O JAR não tem Main-Class no MANIFEST.MF.Correção: Configure a ferramenta de build para gerar um fat JAR. No Maven, use maven-shade-plugin ou spring-boot-maven-plugin.

OutOfMemoryError: Java heap space

Causa: O heap da JVM excede a memória alocada ao container.Correção: Aplicações Java precisam de 512 MB+. Limite o heap:

START=java -Xmx256m -Xms128m -jar app.jar

PHP

Dependências não instaladas / composer.json não encontrado

Causa: O composer.json não está na raiz, ou a pasta vendor/ foi enviada (o que pode ser incompatível).Correção: Inclua o composer.json e o composer.lock na raiz. Não envie a pasta vendor/.

Bots do Discord

An invalid token was provided / Improper token

Causa: O token do bot é inválido, expirou ou foi gerado de novo.Correção:

Gere um novo token no Discord Developer Portal
Defina-o como variável de ambiente (não o deixe fixo no código)
Reinicie a aplicação depois de atualizá-lo

Used disallowed intents / DisallowedIntents

Causa: O bot usa intents privilegiados que não estão habilitados no Developer Portal.Correção: Discord Developer Portal → Bot → Privileged Gateway Intents → ative:

Message Content Intent (para ler o conteúdo das mensagens)
Server Members Intent (para eventos de membros)
Presence Intent (para o status de presença)

Valid intents must be provided / ClientMissingIntents

Causa: Nenhum intent foi especificado ao criar o cliente.Correção:

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

O bot fica offline aleatoriamente

Causa: Memória insuficiente causando um encerramento, ou uma versão desatualizada do discord.js/discord.py.Correção:

Aumente a memória alocada
Atualize o discord.js/discord.py para a versão mais recente
Verifique vazamentos de memória

on_message não funciona (discord.py)

Causa: Falta o intent message_content (exigido desde o discord.py 2.0+).Correção:

intents = discord.Intents.default()
intents.message_content = True
client = discord.Client(intents=intents)

Ative também no Developer Portal.

Variáveis de ambiente

Valores undefined / null na configuração

Causa: As variáveis de ambiente não foram configuradas na plataforma.Correção: Configure todas as variáveis pelo painel ou pela API. Nunca fixe valores sensíveis no código. Use um .env.example para documentar quais variáveis são obrigatórias.

O arquivo .env não funciona na plataforma

Causa: A plataforma não lê arquivos .env automaticamente.Correção: Configure as variáveis pelo painel da Vertra Cloud (aba Variáveis de Ambiente) ou pela API. Não dependa do dotenv carregando um arquivo .env em produção.

Introdução

Deploy

Solução de problemas

Erros comuns de deploy na Vertra Cloud e como corrigi-los

Erros da plataforma

Aplicação não inicia / falhando

Erros de deploy

Erros de rede

Erros de banco de dados

Proteções da plataforma

Node.js / JavaScript

TypeScript

Python

Go

Java

PHP

Bots do Discord

Variáveis de ambiente

​Erros da plataforma

​Aplicação não inicia / falhando

​Erros de deploy

​Erros de rede

​Erros de banco de dados

​Proteções da plataforma

​Node.js / JavaScript

​TypeScript

​Python

​Go

​Java

​PHP

​Bots do Discord

​Variáveis de ambiente

Erros da plataforma

Aplicação não inicia / falhando

Erros de deploy

Erros de rede

Erros de banco de dados

Proteções da plataforma

Node.js / JavaScript

TypeScript

Python

Go

Java

PHP

Bots do Discord

Variáveis de ambiente