> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# App não inicia? Verifique o script de start

# Minha aplicação não inicia: Verificando o script de start

Muitas vezes, o motivo de uma aplicação não sair do "chão" na Square Cloud não está em um erro complexo de lógica, mas sim no **"gatilho"** inicial. Se a plataforma não souber exatamente como dar a partida no seu código, ela encerrará o processo antes mesmo de carregar sua primeira linha de função.

---

## 1. Arquivo Principal vs. Comando Personalizado

Existem duas formas de dizer à Square Cloud como sua aplicação deve começar:

*   **Arquivo Principal (Main):** Você aponta diretamente para o arquivo (ex: `index.js` ou `main.py`). A plataforma tentará executá-lo usando o interpretador padrão.
*   **Comando Personalizado (Start Command):** Você define uma linha de comando completa. Esta é a forma recomendada para aplicações que utilizam frameworks ou servidores de produção, pois oferece maior controle.

---

## 2. O Problema do "Path" e Bibliotecas não instaladas

Um erro clássico é tentar executar um comando que não está no "Path" (caminho de execução direta) do sistema. Se você definir um comando que chama uma biblioteca que não foi instalada ou que o sistema não localiza globalmente, a aplicação falhará imediatamente.

**Dica:** Sempre prefira invocar bibliotecas através de seus respectivos gerenciadores (`npm`, `python -m`, etc.), pois eles sabem exatamente onde procurar os arquivos instalados dentro do ambiente da sua aplicação.

---

## 3. Caso Comum: Next.js (Node.js)

Para que o Next.js funcione corretamente na Square Cloud, ele precisa ser tratado como uma aplicação de produção completa:

*   **Configuração de Dependências:** O Next.js deve estar listado em `dependencies` no seu `package.json`, e não em `devDependencies`. Caso contrário, a plataforma não o encontrará durante a execução.
*   **O Comando de Início:** Evite tentar rodar o binário diretamente. Utilize o script do NPM no seu comando de início personalizado:
```bash
    npm run start
```
    Isso garante que o gerenciador de pacotes localize o Next dentro da pasta `node_modules` e execute o processo de forma segura (lembrando que o script `start` no seu `package.json` deve conter `next start -p 80`).

---

## 4. Caso Comum: Webservers Python (Gunicorn)

Em Python, é comum que o comando `gunicorn` não seja encontrado se digitado sozinho no campo de comando de início, pois ele pode não estar no path direto do sistema. A forma mais robusta de garantir a inicialização é utilizando o módulo através do interpretador Python.

*   **Comando Recomendado:**
```bash
    python -m gunicorn --bind 0.0.0.0:80 app:app
```
*   **Por que o `-m`?** O parâmetro `-m` diz ao Python para procurar o módulo dentro das bibliotecas instaladas no ambiente. Isso resolve a maioria dos problemas de "command not found".

---

## 5. Checklist de Diagnóstico

Se a sua aplicação não está iniciando, verifique os seguintes pontos:

1.  **Instalação:** A biblioteca que você está tentando chamar (como o gunicorn ou next) está no seu `package.json` ou `requirements.txt`?
2.  **Sintaxe:** No comando personalizado, você incluiu todos os argumentos necessários, especialmente a porta 80 para webservers?
3.  **Localização:** Se o seu arquivo principal está dentro de uma pasta (ex: `src/main.py`), o seu comando de início reflete esse caminho corretamente?
4.  **Ambiente:** O comando que você configurou funciona localmente se você deletar a sua pasta de ambiente virtual (`venv` ou `node_modules`) e reinstalar tudo do zero?