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

# Erros comuns

> Como resolver falhas frequentes de deploy.

# <Icon icon="code" color="#0516ee" size={30} /> 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ável                         | Como resolver                                    |
| ----------------------------------------- | -------------------------------------- | ------------------------------------------------ |
| `npm ERR! missing script: build`          | Seu `package.json` não tem `build`     | Ajuste `buildCommand` ou adicione script `build` |
| `sh: pnpm: not found`                     | `pnpm` não está disponível no ambiente | Use `npm ci`/`npm run ...` ou Dockerfile         |
| `pip: command not found`                  | Runtime/config errado                  | Selecione runtime Python ou use Dockerfile       |
| `Request Entity Too Large` / upload falha | ZIP acima do limite                    | Reduza 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ável                                | Como resolver                                                    |
| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| `Error: Cannot find module '...'` | Dependências não instaladas ou caminho errado | Confirme `installCommand` e paths; confira `package.json`        |
| `ModuleNotFoundError: ...`        | Dependência Python ausente                    | Confira `requirements.txt` e `pip install -r requirements.txt`   |
| `Permission denied`               | Execução de binário/arquivo sem permissão     | Prefira 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:

| Sintoma                                    | Causa provável          | Como resolver                         |
| ------------------------------------------ | ----------------------- | ------------------------------------- |
| Logs mostram “Listening on 127.0.0.1:3000” | Bind em localhost       | Mude para `0.0.0.0`                   |
| URL abre, mas dá timeout                   | Porta interna incorreta | Alinhe 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.

## Links relacionados

* [Logs e métricas](/projetos/logs-metricas)
* [Portas e domínios](/projetos/portas-dominios)
* [Como usar ambarks.json](/projetos/ambarks-json)