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

# App não inicia: erros de deploy, site e boot

> Corrija uma aplicação que não faz deploy, não inicia ou não carrega: erros de upload, timeout na porta 80, EADDRINUSE, Cannot find module e horários em UTC.

Se a sua aplicação é recusada no upload, cai no boot ou nunca responde, o código de erro ou o log do console quase sempre nomeia o problema exato. Encontre-o abaixo.

## Erros de upload e deploy

Estes códigos voltam do dashboard, da CLI ou da API quando a Square Cloud recusa um upload. Nada é publicado, então corrija a causa e envie de novo.

| Código | O que significa | Como corrigir |
| - | - | - |
| `FILE_TOO_LARGE` | O zip passa de 100 MB. | Deixe de fora a `node_modules`, a saída de build e mídias grandes. Guarde arquivos grandes no [Blob Storage](/pt-br/services/blob). |
| `INSUFFICIENT_MEMORY` | O `MEMORY` está abaixo do mínimo para o tipo de projeto, ou acima da RAM que o seu plano ainda tem livre. | Confira a [RAM mínima](/pt-br/platform/limitations-and-restrictions#requisitos-mínimos-de-recursos). Para liberar RAM, exclua uma aplicação que você não usa, diminua a RAM de outra ou faça upgrade do plano. |
| `MISSING_CONFIG` | Não há `squarecloud.app` nem `squarecloud.config` no nível mais alto do zip, ou o arquivo está vazio. | Compacte o conteúdo da pasta do projeto, não a pasta em si. |
| `MISSING_MEMORY`, `MISSING_DISPLAY_NAME`, `MISSING_VERSION` | Falta um campo obrigatório no arquivo de configuração. | Adicione-o. Veja o [arquivo de configuração](/pt-br/getting-started/config-file#parâmetros-de-configuração). |
| `MISSING_MAIN`, `INVALID_MAIN` | O `MAIN` está ausente, aponta para um arquivo que não está no zip, está vazio ou quebra as regras de nome. | Confira as [regras do `MAIN`](/pt-br/getting-started/config-file#main). |
| `INVALID_VERSION` | O `VERSION` não é `recommended` nem `latest`. | Use um dos dois valores. |
| `INVALID_RUNTIME`, `INVALID_START` | O `RUNTIME` tem um valor desconhecido, ou o `START` passa de 256 caracteres. | Veja [`RUNTIME`](/pt-br/getting-started/config-file#runtime) e [`START`](/pt-br/getting-started/config-file#start). |
| `INVALID_DISPLAY_NAME`, `INVALID_DESCRIPTION` | O nome tem caracteres além de letras, dígitos, espaços, `-` e `_`, ou passa de 32 caracteres; ou a descrição passa de 280. | Veja [`DISPLAY_NAME`](/pt-br/getting-started/config-file#display_name). |
| `INVALID_SUBDOMAIN` | O subdomínio é inválido, reservado ou já está em uso. | Escolha outro nome. Veja [`SUBDOMAIN`](/pt-br/getting-started/config-file#subdomain). |
| `INVALID_DEPENDENCY` | O arquivo de dependências está ausente ou vazio. | Veja [INVALID\_DEPENDENCY](#invalid_dependency) abaixo. |
| `FAILED_EXTRACT` | O arquivo não é um zip válido. | Crie o zip de novo com a opção de compactar do seu sistema ou com `zip -r`. |
| `KEEP_CALM` | Você repetiu uma ação rápido demais. | Veja [KEEP\_CALM](#keep_calm) abaixo. |

### INVALID\_DEPENDENCY

**O que significa:** o upload não tem um arquivo de dependências para a linguagem dele, ou o arquivo está vazio. A Square Cloud verifica se esse arquivo existe na raiz do zip antes de instalar qualquer coisa.

**Como corrigir:** coloque o arquivo de dependências na raiz do zip, ao lado do `squarecloud.app`, e confira que ele não está vazio: `package.json` (Node.js, Bun, Deno), `requirements.txt` ou `pyproject.toml` (Python), `Cargo.toml` (Rust), `Gemfile` (Ruby), `go.mod` ou `go.work` (Go) ou `mix.exs` (Elixir). Depois, envie de novo. Um nome de pacote ou uma versão com erro de digitação aparece mais tarde, como um erro de instalação nos logs.

### KEEP\_CALM

**O que significa:** você, ou uma automação, repetiu uma ação rápido demais, como um reinício, um upload ou um snapshot.

**Como corrigir:** aguarde um pouco e tente de novo. A ação recusada simplesmente não rodou: o `KEEP_CALM` nunca para nem afeta uma aplicação em execução. Se um snapshot falhar com `DAILY_SNAPSHOTS_LIMIT_REACHED`, a cota diária de snapshots do seu plano acabou até o dia seguinte.

## O site não carrega

**O que significa:** a aplicação foi publicada, mas abrir o endereço dela mostra uma destas páginas em vez do seu site:

* **"The website took too long to respond"**: a Square Cloud encontrou a sua aplicação, mas não recebeu resposta dela.
* **"This site couldn't be found"**: nenhum site está publicado nesse endereço.

**Como corrigir um timeout:**

1. Faça o seu servidor escutar na porta `80` e no host `0.0.0.0`. Um servidor preso a `localhost`, `127.0.0.1` ou a qualquer outra porta (3000, 5173, 8080...) fica inacessível. O runtime define as variáveis de ambiente `PORT` e `HOST` com esses valores, então leia-as:

   <CodeGroup>
     ```javascript Node.js (Express) theme={"system"}
     app.listen(process.env.PORT || 3000, process.env.HOST || "0.0.0.0", () => {
       console.log("Server running");
     });
     ```

     ```python Python (Flask) theme={"system"}
     import os

     app.run(host=os.environ.get("HOST", "0.0.0.0"), port=int(os.environ.get("PORT", 3000)))
     ```
   </CodeGroup>
2. Abra os logs: se a aplicação caiu ou ainda está instalando dependências ou fazendo o build, o site ainda não consegue responder. Corrija o erro mostrado ali, ou espere o build terminar.
3. Confira se o `MEMORY` dá espaço suficiente para o build: o build de um framework que fica sem RAM para a aplicação com [`LACK_OF_RAM`](/pt-br/platform/limitations-and-restrictions#lack_of_ram).

**Como corrigir "This site couldn't be found":**

1. Confira o endereço: ele é `https://<SUBDOMAIN>.squareweb.app`, com o subdomínio do seu arquivo de configuração.
2. Se você acabou de fazer o deploy, espere até um minuto para o endereço ser publicado.
3. Uma aplicação enviada sem `SUBDOMAIN` não é um site e não pode virar um: envie-a de novo como uma nova aplicação, com o [`SUBDOMAIN`](/pt-br/getting-started/config-file#subdomain) definido.
4. Em um domínio personalizado, o DNS pode ainda estar propagando. Veja [por que o seu domínio ainda não propagou](https://help.squarecloud.app/pt-br/article/por-que-meu-dominio-ainda-nao-propagou-dns-3ggus4/).

## EADDRINUSE (porta já em uso)

**O que significa:** a aplicação tenta vincular a mesma porta de rede duas vezes.

**Por que acontece:** dois servidores são iniciados no código, ou uma chamada `listen(...)` é criada de novo dentro de um event handler (por exemplo, a cada requisição ou a cada reconexão) em vez de uma única vez na inicialização.

**Como corrigir:**

1. Inicie **um único** servidor web, **uma única vez**, escutando na porta `80` e no host `0.0.0.0`.
2. Procure no seu código por mais de uma chamada `.listen()` (Node.js) ou `run()` (Python/Flask/Django) e remova a duplicada.
3. Garanta que a chamada de listen fique no nível mais alto do seu arquivo de inicialização, não dentro de um callback que pode disparar mais de uma vez.

## "Cannot find module" (Node.js) e ModuleNotFoundError (Python)

**O que significa:** um pacote que o seu código importa não está instalado.

**Por que acontece:**

* A biblioteca não está listada em `dependencies` do `package.json` (Node.js) nem em `requirements.txt`/`pyproject.toml` (Python), então ela nunca é instalada na plataforma, mesmo que funcione na sua máquina.
* No Node.js, o pacote está só em `devDependencies`. As aplicações rodam com `NODE_ENV=production`, então o `npm install` pula as dependências de desenvolvimento.

**Como corrigir:**

1. Adicione o pacote ausente a `dependencies` (ou ao seu arquivo de dependências do Python) com uma versão válida.
2. Confirme que o próprio arquivo de dependências está no zip que você enviou.
3. Reinicie a aplicação. No Node.js, as dependências só são instaladas quando a `node_modules` não existe: apague a `node_modules` (e o `package-lock.json`, se você enviou um) no gerenciador de arquivos do dashboard e reinicie para uma reinstalação limpa.

## Erros de bindings nativos do better-sqlite3

**O que significa:** um erro como `Could not locate the bindings file` quando a sua aplicação usa o `better-sqlite3` (diretamente, ou pelo `quick.db`).

**Por que acontece:** a versão instalada do `better-sqlite3` é anterior à LTS atual do Node.js na plataforma, então o binding nativo pré-compilado dela não corresponde ao runtime.

**Como corrigir:**

1. Atualize o `better-sqlite3` para `12.5.0` ou posterior (se você usa o `quick.db`, atualize-o para `9.1.7` ou posterior).
2. Apague a `node_modules` **e** o `package-lock.json`.
3. Reinicie a aplicação para uma reinstalação limpa, que reconstrói os bindings nativos para o runtime atual.

## Parada por um limite de recursos

Se os logs terminam com `[SQUARE-SHIELD] LACK_OF_RAM`, `LACK_OF_CPU` ou `ABUSE_REQUESTS`, ou se iniciar a aplicação falha com `CONTAINER_TEMPORARILY_SUSPENDED`, a Square Cloud a parou por passar dos seus recursos. A [tabela de status](/pt-br/platform/limitations-and-restrictions#status-de-limite-excedido) explica cada um e como corrigir.

## Horários com algumas horas de diferença

As aplicações rodam em UTC. Uma tarefa agendada para 09:00 roda às 09:00 UTC, e os horários que o seu código imprime nos logs estão em UTC. Converta os horários no seu código, ou veja [como alterar o fuso horário da aplicação](https://help.squarecloud.app/pt-br/article/como-alterar-o-fuso-horario-timezone-da-aplicacao-1in95bs/) na central de ajuda.

## Guias relacionados

* [Arquivo de configuração](/pt-br/getting-started/config-file): todos os campos e o erro que cada um gera.
* [Variáveis de ambiente](/pt-br/platform/environment-variables): defina os segredos e reinicie para aplicá-los.
* [Erros do bot do Discord](/pt-br/platform/troubleshooting/discord-bot-errors) e [erros de conexão com banco de dados](/pt-br/platform/troubleshooting/database-connection-errors).

<Tip>Ainda travado depois de conferir os logs com os erros acima? Nossa equipe de suporte pode analisar a falha específica com você.</Tip>

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


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