blog
Infraestrutura web

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.

JR · · 7 min de leitura · 2 tabelas · 10 blocos de código

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
  1. O que o Setup Python App monta por baixo
  2. Por que o Passenger procura `application` e ignora `app`
  3. Por que o `pip install` some se você não ativar o virtualenv do painel
  4. Por que estático entregue pelo worker vira 500 e desperdício
  5. Onde o traceback aparece: log da aplicação, não error_log do domínio
  6. `touch tmp/restart.txt` é o que faz o código novo valer
  7. 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:

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:

  1. 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.
  2. 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.

# 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.

Do sintoma a causa no Passenger500 em toda URLAbra o log da aplicacaoFalta objeto applicationAlias no arquivo de entradaModuleNotFoundErrorAtive o venv e reinstale400 DisallowedHostInclua o dominio em ALLOWED_HOSTSEstatico retorna text/htmlAlias ou PassengerEnabled offCodigo antigo no artouch tmp/restart.txt
Caminho de diagnostico a partir do sintoma observado no navegador e no log da aplicacao.

`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

  1. source da ativação exibida pelo painel.
  2. git pull ou upload do código.
  3. pip install -r requirements.txt.
  4. python manage.py migrate (Django).
  5. python manage.py collectstatic --noinput (Django).
  6. touch tmp/restart.txt.
Ordem de deploy sem 500 intermediariosource do venvLinha exata exibida pelo painelAtualizar codigogit pull ou uploadpip installrequirements.txt travadomigrate e collectstaticApenas em projetos Djangotouch tmp/restart.txtSempre o ultimo passo
Ordem de deploy que evita 500 intermediario entre a troca de codigo e o restart do worker.

Checklist antes de abrir chamado

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

  1. Documentação oficial (cpanel) — How to Install a Python WSGI Application. Consultado em 2026-10-14.
Leia também