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.

Resposta curta: 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.
Neste artigo
- O que o Setup Python App monta por baixo
- Por que o Passenger procura `application` e ignora `app`
- Por que o `pip install` some se você não ativar o virtualenv do painel
- Por que estático entregue pelo worker vira 500 e desperdício
- Onde o traceback aparece: log da aplicação, não error_log do domínio
- `touch tmp/restart.txt` é o que faz o código novo valer
- Checklist antes de abrir chamado
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 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
gunicornescutando numa porta sua para você testar comcurl 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.
# 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:
# 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:
# 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.
# 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:
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 descreve para a interface do Setup Python App.
PassengerEnabled offnum.htaccesscolocado 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 terAllowOverriderestrito.
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.
# settings.py (exemplo)
DEBUG = False
ALLOWED_HOSTS = ['exemplo.com.br', 'www.exemplo.com.br']
STATIC_URL = '/static/'
STATIC_ROOT = '/home/usuario/public_html/static'
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.
# 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 |
# 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:
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
sourceda ativação exibida pelo painel.git pullou 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
applicationno escopo de módulo. which python, após osource, aponta para dentro devirtualenv/.pip freezedentro do venv lista Flask ou Django.ALLOWED_HOSTScontém o domínio e owww, comDEBUG = False.STATIC_ROOTestá fora do Application root ecollectstaticrodou.curl -Iem um arquivo estático devolve 200 comContent-Typecorreto.tail -fno log da aplicação, no caminho que o painel exibe, mostra o traceback no instante do request.touch tmp/restart.txtfoi 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; os blocos de código são exemplos, com caminhos e nomes de projeto fictícios que você precisa substituir pelos seus.
Referências
- Documentação oficial (cpanel) — How to Install a Python WSGI Application. Consultado em 2026-10-14.