# As 4 causas do erro 500 em Flask e Django no cPanel

O que o campo Application startup file espera de verdade, por que o virtualenv do painel só vale com a linha de ativação que ele exibe, e qual log abrir quando o 500 aparece.

> o 500 depois de criar o app no Setup Python App tem 4 causas: o arquivo de entrada não expõe um chamável `application`, o `pip install` rodou fora do virtualenv do painel, os estáticos passam pelo Passenger, ou você lê o error_log do domínio em vez do log da aplicação.

João Rizzon · 2026-10-17 · Infraestrutura web

---

Você criou o app em **Setup Python App**, apontou para a pasta, clicou em Create e abriu o domínio. Veio 500. O painel não mostra o motivo, e o `error_log` do domínio não diz nada útil. O problema quase sempre está em um de quatro pontos: o nome do objeto chamável no arquivo de entrada, o virtualenv que você não ativou antes do `pip install`, os estáticos passando pelo Passenger e o log errado sendo lido.

## O que o Setup Python App monta por baixo

O recurso do cPanel provisiona um interpretador Python isolado e registra a aplicação no **Phusion Passenger**, que fica embutido no servidor web. A [documentação oficial do cPanel](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-python-wsgi-application/) descreve o fluxo: você informa a versão do Python, o **Application root** (diretório da aplicação, relativo à home), a **Application URL** (domínio ou domínio + caminho) e o **Application startup file**.

Não há processo que você mesmo sobe. O Passenger inicia o worker sob demanda, na primeira requisição, com o usuário do cPanel. Isso tem três consequências práticas que mudam o jeito de depurar:

- Não existe `gunicorn` escutando numa porta sua para você testar com `curl localhost:8000`. O ponto de entrada é importado pelo Passenger.
- Variáveis de ambiente que você exporta no shell não chegam ao worker. Só valem as definidas no próprio painel (seção de variáveis de ambiente da aplicação) ou dentro do código.
- Reiniciar não é matar processo: é sinalizar o Passenger.

## Por que o Passenger procura `application` e ignora `app`

Este é o erro mais comum com Flask. O arquivo apontado em **Application startup file** (por padrão `passenger_wsgi.py`) precisa expor, no escopo de módulo, um objeto chamável WSGI chamado **`application`**. Não é `app`. Não é `main`. O Passenger importa o módulo e procura esse nome.

Flask, pelo tutorial padrão, cria `app = Flask(__name__)`. Sozinho, isso não publica nada. É preciso o alias explícito.

```python
# passenger_wsgi.py (exemplo, Flask)
from myapp import app as _flask_app

# o Passenger procura exatamente este nome
application = _flask_app
```

Se a factory pattern for usada (`create_app()`), o alias chama a factory:

```python
# passenger_wsgi.py (exemplo, Flask com factory)
from myapp import create_app

application = create_app()
```

Django já gera o chamável no arquivo `wsgi.py` do pacote do projeto, e ele já se chama `application`. O arquivo de entrada vira uma ponte de uma linha:

```python
# passenger_wsgi.py (exemplo, Django)
import os
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'meuprojeto.settings')

from meuprojeto.wsgi import application  # noqa: F401
```

Se preferir, aponte o **Application startup file** direto para `meuprojeto/wsgi.py` no painel, já que ele atende ao contrato. Manter o `passenger_wsgi.py` na raiz, porém, dá um lugar para ajustar `sys.path` e variáveis sem mexer no projeto.

| Framework | Objeto gerado pelo framework | O que o arquivo de entrada precisa ter |
|---|---|---||
| Flask | `app = Flask(__name__)` | `application = app` (ou `application = create_app()`) |
| Django | `application` em `projeto/wsgi.py` | `from projeto.wsgi import application` |
| FastAPI/Starlette | `app` ASGI | Não é WSGI puro: precisa de adaptador (`a2wsgi`) ou outro modelo de deploy |

## Por que o `pip install` some se você não ativar o virtualenv do painel

Ao criar a aplicação, o cPanel cria um ambiente virtual próprio e **exibe na interface a linha de comando de ativação**, no formato `source /home/USUARIO/virtualenv/CAMINHO/VERSAO/bin/activate && cd /home/USUARIO/CAMINHO`. A documentação instrui a copiar essa linha e executá-la no terminal antes de instalar dependências.

O motivo é direto: um `pip install` fora dessa ativação instala no Python do sistema ou no `--user` da conta, e o worker do Passenger não vai enxergar o pacote. O sintoma é `ModuleNotFoundError` no log mesmo depois de o `pip install` ter dito Successfully installed.

```bash
# cole a linha exata que o painel mostrar; o caminho muda por app
source /home/usuario/virtualenv/apps/loja/3.11/bin/activate && cd /home/usuario/apps/loja

# confirme ANTES de instalar qualquer coisa
which python
python -V

pip install -r requirements.txt
```

Se `which python` não apontar para dentro de `virtualenv/`, pare e refaça a ativação. Alternativa sem shell: o painel também aceita um arquivo `requirements.txt` na raiz da aplicação e oferece a execução do `pip install` pela própria interface.

### Por que travar as versões na máquina de desenvolvimento, não no servidor

Gere o `requirements.txt` com versões travadas na máquina de desenvolvimento, não no servidor:

```bash
pip freeze > requirements.txt
```

O servidor compartilhado pode não ter toolchain de compilação disponível para toda extensão C. Pacotes com wheel pronto para a versão do CPython escolhida instalam sem drama; os que exigem build podem falhar. Quando falhar, leia a saída do `pip` inteira, não só a última linha: o erro real costuma estar algumas dezenas de linhas acima.

## Por que estático entregue pelo worker vira 500 e desperdício

Todo request que cai no caminho da aplicação é entregue ao worker Python. Para CSS, JS e imagens, isso é desperdício de processo e fonte de 500 bobo. Há duas vias:

- **Static Files / alias na configuração da aplicação**, mapeando um prefixo de URL para um diretório no disco. É o que a [documentação do cPanel](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-python-wsgi-application/) descreve para a interface do Setup Python App.
- **`PassengerEnabled off`** num `.htaccess` colocado dentro do próprio diretório de estáticos. É diretiva do Passenger para Apache, não um parâmetro do painel: o Apache passa a entregar os arquivos daquele diretório sem invocar o worker. Teste no seu domínio antes de publicar, porque o servidor pode ter `AllowOverride` restrito.

No caso do Django, isso se combina com `collectstatic`. O `STATIC_ROOT` precisa apontar para um diretório **fora** do Application root, tipicamente dentro de `public_html`, para que o alias funcione e para que ninguém baixe seu código-fonte por URL.

```python
# settings.py (exemplo)
DEBUG = False
ALLOWED_HOSTS = ['exemplo.com.br', 'www.exemplo.com.br']

STATIC_URL = '/static/'
STATIC_ROOT = '/home/usuario/public_html/static'
```

```bash
source /home/usuario/virtualenv/apps/loja/3.11/bin/activate && cd /home/usuario/apps/loja
python manage.py collectstatic --noinput
python manage.py migrate
```

Com `ALLOWED_HOSTS` sem o domínio, o Django levanta `DisallowedHost`, que é uma `SuspiciousOperation`, e responde **400**, não 500. O registro sai no log da aplicação, e não é erro do Passenger: 400 em toda rota com `DEBUG = False` aponta para essa lista antes de qualquer outra coisa. Com `DEBUG = True` em produção você expõe settings, trechos de código e caminhos a quem provocar uma exceção. Não deixe ligado nem "só para ver o erro": o log resolve isso melhor.

### Servindo /static pelo .htaccess

Quando a aplicação está na raiz do domínio, o `.htaccess` vai **dentro do diretório estático**, nunca em `public_html`. `PassengerEnabled off` em `public_html/.htaccess` desliga o Passenger para o domínio inteiro e derruba a aplicação. E `RewriteRule ^static/ - [L]` não serve aqui: o rewrite só decide o caminho, o request continua sendo entregue ao worker.

```apache
# public_html/static/.htaccess (exemplo)
# vale só para este diretório e o que estiver abaixo dele
PassengerEnabled off
```

Valide sempre com `curl -I https://exemplo.com.br/static/app.css` e confira `Content-Type` e `200`. Se vier `text/html`, o request ainda está indo para a aplicação.

## Onde o traceback aparece: log da aplicação, não error_log do domínio

O `error_log` do domínio registra o que o servidor web viu: normalmente só "a aplicação retornou erro". O traceback do Python sai no stderr do worker, que o Passenger grava no caminho de log exibido pelo painel no card da aplicação. Esse caminho varia conforme a versão do cPanel e a configuração do servidor, então confirme o seu no painel em vez de caçar arquivo por nome. Procure nessa ordem:

| Sintoma | Onde olhar primeiro | Causa típica |
|---|---|---||
| 500 em toda URL, inclusive `/` | log da aplicação (caminho do painel) | `application` ausente, `ModuleNotFoundError`, erro de import |
| 500 só em algumas rotas | log da aplicação (caminho do painel) | exceção de runtime, banco, permissão de arquivo |
| 404 em `/static/...` | `error_log` do domínio | alias ausente, `collectstatic` não rodado |
| Página antiga depois do deploy | nenhum: é cache de processo | falta `touch tmp/restart.txt` |
| 400 com `DisallowedHost` | log da aplicação (caminho do painel) | `ALLOWED_HOSTS` sem o domínio |

```bash
# troque pelo caminho de log que o painel exibe para a aplicação
tail -n 100 -f /home/usuario/CAMINHO_DE_LOG_DO_APP
```

Ajuste o caminho para o diretório de log que o painel indica na aplicação. Com o `tail -f` aberto, recarregue a URL no navegador: o traceback aparece no momento do request, o que elimina a dúvida sobre qual erro é o seu.

## `touch tmp/restart.txt` é o que faz o código novo valer

O Passenger mantém o worker vivo entre requisições. Alterar `.py` não recarrega nada sozinho em modo de produção. O gatilho é o arquivo de restart dentro do Application root:

```bash
cd /home/usuario/apps/loja
mkdir -p tmp
touch tmp/restart.txt
```

O botão **Restart** do painel faz o equivalente. Use o `touch` em scripts de deploy, como último passo, depois de `pip install`, `migrate` e `collectstatic`. A reversão é igualmente simples: volte o código, rode o `touch` de novo.

### Ordem de deploy que evita 500 intermediário

- `source` da ativação exibida pelo painel.
- `git pull` ou upload do código.
- `pip install -r requirements.txt`.
- `python manage.py migrate` (Django).
- `python manage.py collectstatic --noinput` (Django).
- `touch tmp/restart.txt`.

## Checklist antes de abrir chamado

- O arquivo em **Application startup file** define `application` no escopo de módulo.
- `which python`, após o `source`, aponta para dentro de `virtualenv/`.
- `pip freeze` dentro do venv lista Flask ou Django.
- `ALLOWED_HOSTS` contém o domínio e o `www`, com `DEBUG = False`.
- `STATIC_ROOT` está fora do Application root e `collectstatic` rodou.
- `curl -I` em um arquivo estático devolve 200 com `Content-Type` correto.
- `tail -f` no log da aplicação, no caminho que o painel exibe, mostra o traceback no instante do request.
- `touch tmp/restart.txt` foi o último comando do deploy.

O que este guia **não** mede: tempo de cold start do worker, consumo de memória por processo Passenger ou throughput comparado a um `gunicorn` dedicado. Esses números dependem do seu código e do servidor, e não foram medidos aqui. Os parâmetros e campos descritos vêm da [documentação do cPanel sobre instalação de aplicação Python WSGI](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-python-wsgi-application/); os blocos de código são exemplos, com caminhos e nomes de projeto fictícios que você precisa substituir pelos seus.

