> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Sintoma, causa e correção dos erros de deploy mais frequentes na Vertra Cloud: OOMKilled, crash loop, módulo ausente, timeout e token inválido.

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:**
>
> ```js theme={null}
> 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?](https://docs.vertracloud.app/pt-br/databases.md#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`:
>
> ```bash theme={null}
> 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`:
>
> ```json theme={null}
> {
>   "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`:
>
> ```json theme={null}
> {
>   "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`:
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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:
>
> ```python theme={null}
> 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:**
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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](https://discord.com/developers/applications)
> * 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:**
>
> ```js theme={null}
> 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:**
>
> ```python theme={null}
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.