Skip to main content

​
Troubleshooting

Use esta página para diagnosticar problemas comuns ao publicar uma aplicação.

​
Deploy fica pendente por muito tempo

O que fazer:
  • Atualize a página e confira se houve mudança de status.
  • Veja os logs do projeto.
  • Tente iniciar um novo deploy.
  • Se persistir, entre em contato com o suporte informando o nome do projeto.
Observação: o job de deploy tem timeout de 15 minutos por tentativa. Se estourar, o deploy tende a falhar e você verá o motivo nos logs.

​
Build falhou

Verifique:
  • Dependências foram incluídas corretamente.
  • Lockfiles estão presentes quando usados pelo projeto.
  • O comando de instalação em ambarks.json funciona localmente.
  • O projeto não depende de arquivos que ficaram fora do ZIP ou do repositório.
Mensagens comuns e causas prováveis:
Erro (exemplo)Causa provávelComo resolver
npm ERR! missing script: buildSeu package.json não tem buildAjuste buildCommand ou adicione script build
sh: pnpm: not foundpnpm não está disponível no ambienteUse npm ci/npm run ... ou Dockerfile
pip: command not foundRuntime/config erradoSelecione runtime Python ou use Dockerfile
Request Entity Too Large / upload falhaZIP acima do limiteReduza o .zip (máximo 100 MB)

​
Comando de start falhou

Verifique:
  • run.command em ambarks.json.
  • Script start no package.json, se for Node.js.
  • Arquivo de entrada, como main.py, server.js ou equivalente.
  • Variáveis de ambiente exigidas pela aplicação.
Mensagens comuns e causas prováveis:
Erro (exemplo)Causa provávelComo resolver
Error: Cannot find module '...'Dependências não instaladas ou caminho erradoConfirme installCommand e paths; confira package.json
ModuleNotFoundError: ...Dependência Python ausenteConfira requirements.txt e pip install -r requirements.txt
Permission deniedExecução de binário/arquivo sem permissãoPrefira comandos via node, python, bash -lc, ou Dockerfile

​
Deploy conclui, mas site não abre

Verifique:
  • Porta interna configurada no projeto.
  • Porta usada pelo comando de start.
  • EXPOSE no Dockerfile, se houver.
  • Se a aplicação escuta em 0.0.0.0 (e não em 127.0.0.1).
Mensagens comuns e causas prováveis:
SintomaCausa provávelComo resolver
Logs mostram “Listening on 127.0.0.1:3000”Bind em localhostMude para 0.0.0.0
URL abre, mas dá timeoutPorta interna incorretaAlinhe porta interna + PORT + start

​
Variável de ambiente não aparece

Verifique:
  • Se a variável foi salva no projeto correto.
  • Se houve novo deploy após a alteração.
  • Se o nome da variável está igual ao esperado pelo código.
  • Se ela precisa estar disponível durante o build (use “Build arg”).

​
Repositório GitHub não publica

Verifique:
  • Se a conta GitHub está conectada.
  • Se o repositório ainda existe e você tem permissão.
  • Se a branch selecionada contém os arquivos do projeto.
  • Se o projeto privado continua acessível pela integração.