# Problemas comuns

Esta página reúne os problemas mais comuns ao publicar na Nebular, o que cada um significa e o que fazer. Comece pelo log: na aba **Deploys** do projeto, clique em **Ver log** na versão que falhou. Para a lista técnica de códigos, veja a [Tabela de erros](/erros/tabela/).

## O build falhou

O deploy aparece como **Falhou**. A mensagem diz em que etapa parou, por exemplo "clonar o repositório", "instalar as dependências" ou "executar o build".

| Etapa | O que fazer |
|---|---|
| Clonar o repositório | Confira a URL, a branch e o acesso. Para repositório privado, use **Conectar GitHub (repos privados)** ou um token. |
| Detectar a stack | Confirme que a raiz tem `package.json`, `Dockerfile` ou `index.html`. |
| Instalar dependências ou executar o build | Rode o mesmo comando na sua máquina e corrija o erro que o log mostrar. |
| Falta de memória ou tempo esgotado | O build usa mais recursos do que o permitido. Reduza o trabalho do build ou divida o projeto. |

Depois de corrigir, publique de novo. Passo a passo: [Corrigir um deploy](/agents/corrigir-deploy/).

## O app não sobe

O build terminou, mas a nova versão não ficou no ar. A versão anterior continua servindo o site. Os motivos mais comuns:

| Mensagem | O que fazer |
|---|---|
| O app parou logo ao iniciar | Veja as últimas linhas do log: costuma ser erro de código ou variável faltando. |
| O app está rodando, mas não respondeu na porta N | Faça o app escutar em `0.0.0.0` na porta da variável `PORT`. |
| O app usou mais memória do que o limite do serviço | Aumente a memória em [Escala e recursos](/operacao/escala-e-recursos/) ou reduza o consumo. |
| O app tentou gravar em uma pasta | O disco do app é somente leitura, exceto `/tmp`. Grave em um banco ou em um [volume](/conectados/volumes/). |
| A imagem roda como root | Use uma imagem sem root ou informe o usuário de execução. Veja [Dockerfile](/guia/dockerfile/). |

## Erro 502 ou o site não abre

Um 502 quer dizer que a plataforma não conseguiu falar com o seu app. Confira, nesta ordem:

1. O último deploy está **No ar**? Se não, veja o log do deploy.
2. O app escuta na porta certa? A porta padrão é 3000, e a plataforma entrega a porta na variável `PORT`.
3. O app demora para iniciar? A janela inicial do health check é de 60 segundos por padrão e pode ser ampliada (até 900) nas configurações do site.
4. O **Log de execução** mostra erro ou reinício constante? Abra a aba **Logs** do site.

Veja também [Logs, métricas e tráfego](/operacao/observabilidade/).

## Domínio pendente

Na aba **Domínios** do site, o selo **Aguardando DNS** ou **Verificando** significa que a plataforma ainda não achou os registros certos. **Com erro** traz o motivo. Crie os registros que o painel mostra, espere propagar e use a verificação. Mudar só os nameservers não basta. Guia completo: [Problemas comuns de domínio](/dominios/problemas-comuns/).

## Sem espaço no servidor

Se o deploy falha com `build_disk_full`, `build_storage_unavailable` ou `build_storage_error`, o problema está do lado da plataforma, não no seu código. O deploy não fica esperando: espere alguns minutos e refaça. Se repetir, avise o suporte com o id do deploy. Detalhes: [Fila de build](/operacao/fila-de-build/).

## Cota excedida

A resposta `quota_exceeded` (HTTP 422) diz qual limite foi atingido. As mensagens são:

| Mensagem | O que fazer |
|---|---|
| Limite de projetos do plano atingido. | Apague ou mova para a lixeira um projeto que não usa mais. |
| Limite de serviços do plano atingido. | Remova um serviço ou peça um plano maior. |
| Limite de bancos do plano atingido. | Remova um banco que não usa. |
| Limite de volumes do plano atingido. | Remova um volume ou reduza o pedido. |
| Limite de N domínios por serviço (ou por time) atingido. | Remova um domínio que não usa. |
| Limite de variáveis atingido. | Reduza a quantidade ou o tamanho. |

Itens na lixeira continuam ocupando espaço até serem apagados de vez. Veja [Limites e cotas](/operacao/limites-e-cotas/) e [Lixeira](/operacao/lixeira/).

## Limite de deploys por hora

Ao passar do limite de deploys do time, a resposta é `429 rate_limited` com a mensagem "Limite de deploys por hora do plano atingido." O limite conta todos os projetos do time juntos, em uma janela de 1 hora. Espere o tempo do cabeçalho `Retry-After` e tente de novo. Não é falha permanente. Veja [Rate limit e retry](/erros/rate-limit-e-retry/).

## Upload grande demais

No painel, o envio aceita `.html`, `.zip`, `.tar`, `.tar.gz` e `.tgz` de até 250 MB. As mensagens são: "Esse formato ainda não é aceito. Envie um .html, .zip, .tar, .tar.gz ou .tgz.", "Esse arquivo está vazio. Escolha outro para enviar." e "Esse arquivo passa de 250 MB. Tente compactar ou remover o que não é necessário." Remova `node_modules` e arquivos de build do pacote. Por API, o envio direto aceita cerca de 25 MB; prefira [deploy por Git](/comecar/deploy-por-git/) para projetos grandes. Arquivos de galeria têm limite de 25 MB.

## Banco somente leitura

Quando o banco passa da cota, ele fica **Somente leitura**: leituras funcionam, gravações falham. Ele volta ao normal sozinho quando o uso cai abaixo do limite. Apague dados ou aumente a cota na aba **Bancos**. Veja [Postgres](/bancos/postgres/).

## Se nada resolver

Anote o id do deploy e o horário, copie as últimas linhas do log e fale com o suporte. Para um agent corrigir sozinho, use [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/).

## Próximos passos

- [Tabela de erros](/erros/tabela/)
- [Deploys e status](/operacao/deploys-e-status/)
- [Limites e cotas](/operacao/limites-e-cotas/)
