Formulário CGI com erro 500: as quatro causas e o log
Cada mensagem do error_log aponta para uma causa só. O mapa, o checklist para auditar a carteira inteira e a frase pronta para o cliente que jura que ninguém mexeu.

Resposta curta: são quatro as causas mais frequentes de 500 em script .cgi ou .pl herdado: permissão fora de 755 ou dono errado no suEXEC, shebang para interpretador inexistente, CRLF de upload FTP e pasta sem CGI habilitado. O error_log diz literalmente qual delas é.
Neste artigo
- Por que um CGI parado há dez anos volta a dar 500 sem ninguém tocar nele
- Onde está o log certo (e por que o log do PHP não serve aqui)
- Que causa cada família de mensagem do error_log aponta
- As quatro causas e a verificação que confirma cada uma
- Como auditar trinta sites antes da próxima migração quebrar um deles
- Como padronizar para não reincidir
- O que dizer ao cliente que jura que ninguém mexeu no formulário
- O que este artigo não mede
Por que um CGI parado há dez anos volta a dar 500 sem ninguém tocar nele
O cenário é sempre parecido. A agência assume um site antigo, ou o cliente muda de hospedagem, ou o servidor atual ganha uma versão nova do painel. O WordPress continua de pé, as páginas abrem, e só o contato.cgi da pasta cgi-bin passa a devolver 500 Internal Server Error. O arquivo não mudou. O que mudou foi o ambiente ao redor dele.
CGI roda como um processo novo a cada requisição, disparado pelo suEXEC com o usuário da conta. O PHP moderno em cPanel roda em pool persistente (PHP-FPM), com o seu próprio dono de processo e o seu próprio log. São dois caminhos de execução diferentes, e é por isso que o CGI tem exigências que o PHP não tem: o arquivo precisa ser executável pelo dono correto, a primeira linha precisa apontar para um binário que existe naquele servidor, e o conteúdo precisa estar em um formato que o kernel consiga ler. Em servidor antigo, várias dessas exigências eram frouxas. Em servidor atual com suEXEC ligado, não são.
A boa notícia para quem cobra por hora: o error_log de CGI é muito mais específico que o de PHP. Cada uma das quatro causas clássicas produz uma mensagem diferente. Se você souber ler a linha literal, o diagnóstico leva menos tempo que abrir o FTP.
Onde está o log certo (e por que o log do PHP não serve aqui)
Antes de qualquer coisa, achar a linha. Em servidor cPanel, você tem normalmente três lugares para olhar:
- Erros do painel: a seção de erros do cPanel mostra as últimas linhas do log de erro do Apache referentes àquela conta, a que você está logado. É o caminho mais rápido quando você não tem SSH.
- Log de erro do domínio: dentro da conta, costuma ficar em
~/logs/, com um arquivo por domínio. Em instalações mais antigas você ainda encontra umerror_logsolto dentro depublic_html. - Log do suexec: fica fora da conta, no diretório de logs do Apache (em EasyApache 4, tipicamente
/etc/apache2/logs/suexec_log). Sem root você não lê. Se a suspeita for permissão ou dono, peça ao suporte o trecho desse arquivo no horário do teste. É um pedido objetivo e eles costumam responder rápido.
A documentação da cPanel sobre troubleshooting de Perl e CGI trata o log de erro do Apache como primeira parada do diagnóstico, junto com permissão do arquivo, modo de upload e caminho do interpretador. É exatamente essa ordem que o checklist mais abaixo segue.
Uma armadilha comum: o log de erro do PHP (ou o debug.log do WordPress) não registra nada de CGI. Se o script está em cgi-bin, quem o executa é o Apache via suEXEC, e a mensagem só aparece no log de erro do domínio ou no suexec_log. Procurar no lugar errado é o que transforma um diagnóstico de dez minutos em uma tarde perdida.
Para reproduzir o erro na hora certa e não caçar linha antiga, faça isto com SSH aberto:
# terminal 1: acompanhe o log do domínio
tail -f ~/logs/exemplo.com.br.error.log
# terminal 2: dispare o script pela rede, como o navegador faria
curl -s -o /dev/null -w '%{http_code}\n' https://exemplo.com.br/cgi-bin/contato.cgi
O curl devolve 500 e a linha nova no log é a sua evidência. Guarde o texto literal. A tabela da próxima seção trabalha em cima dele.
Que causa cada família de mensagem do error_log aponta
As mensagens variam um pouco conforme a versão do Apache e do suexec. O que não varia é o padrão: cada família de mensagem aponta para uma causa diferente, e elas não se confundem entre si.
| Mensagem no error_log (trecho literal) | Causa provável | Verificação |
|---|---|---|
No such file or directory: exec of '/home/.../contato.cgi' failed |
Shebang apontando para interpretador que não existe nesse caminho, ou \r grudado no fim da primeira linha |
cat -A contato.cgi (procurar ^M$ na primeira linha) e which perl |
Exec format error: exec of '...' failed |
Shebang ausente, malformado, ou arquivo com quebra de linha CRLF | file contato.cgi |
Premature end of script headers ou End of script output before headers |
O script rodou mas morreu antes de imprimir o cabeçalho, ou nunca imprimiu Content-Type |
perl -cw contato.cgi e execução manual no shell |
Linhas no suexec_log com uid/gid mismatch, file has no execute permission ou directory is writable by others |
Permissão diferente de 755 ou dono/grupo fora do padrão da conta | ls -l no arquivo e na pasta |
Options ExecCGI is off in this directory ou .htaccess: Option ExecCGI not allowed here |
Pasta fora do diretório habilitado para CGI, ou .htaccess tentando ligar algo que o servidor não permite |
mover o script para cgi-bin e testar |
| Navegador mostra o código-fonte do script em vez de executar | Handler de CGI não aplicado àquela extensão naquela pasta | mesma verificação acima |
Os caminhos e nomes de arquivo nas linhas acima são exemplos. O que você compara é a forma da mensagem, não o caminho.
As quatro causas e a verificação que confirma cada uma
Permissão fora de 755 ou dono errado faz o suEXEC recusar o arquivo
O suEXEC roda o script com o usuário da conta e, antes disso, confere um conjunto de condições. Se qualquer uma falhar, ele aborta e o Apache devolve 500. As duas mais comuns depois de migração: arquivo sem bit de execução e arquivo restaurado com dono diferente do usuário da conta (acontece quando um backup é descompactado como root).
A documentação da cPanel trata 0755 como a permissão de trabalho para scripts Perl e CGI. Mais que isso não ajuda e atrapalha: pasta ou arquivo gravável por outros faz o suEXEC recusar, então chmod 777, o velho reflexo de quem herdou site antigo, é o oposto da correção.
# situação atual
ls -l ~/public_html/cgi-bin/
# correção
chmod 755 ~/public_html/cgi-bin/contato.cgi
chmod 755 ~/public_html/cgi-bin
Se o ls -l mostrar dono diferente do usuário da conta, chown não vai funcionar sem root. Esse é o caso em que você abre chamado com o trecho do suexec_log em mãos e pede a correção de propriedade. Na prática é a única das quatro causas que você não resolve sozinho de dentro da conta.
Shebang apontando para um interpretador que não existe no servidor
A primeira linha do script diz ao kernel qual binário executar. Se ela diz #!/usr/local/bin/perl e o servidor tem o Perl em /usr/bin/perl, o Apache registra No such file or directory no exec of, e não no arquivo do script. Muita gente lê essa mensagem e vai procurar o arquivo que está lá, intacto. O arquivo faltando é o interpretador.
head -1 ~/public_html/cgi-bin/contato.cgi
which perl
Se os dois não baterem, ajuste a primeira linha para o caminho que o which devolveu. Em cPanel o caminho usual é /usr/bin/perl, e é ele que a documentação usa como referência nos exemplos de shebang.
Um detalhe que economiza retrabalho em carteira grande: se o site vive migrando, prefira o shebang que o servidor resolve por PATH em vez do caminho fixo, quando o script aceitar. Mas teste, porque nem todo ambiente com suEXEC se comporta igual, e shebang com env pode ter tratamento diferente. Valide com um curl antes de replicar em vinte sites.
CRLF de upload FTP em modo binário quebra a primeira linha
Essa é a causa que mais confunde, porque o arquivo parece perfeito no editor. Script criado ou editado no Windows, ou enviado por FTP em modo binário quando deveria ir em ASCII, chega ao servidor com \r\n no fim de cada linha. O kernel lê a primeira linha como /usr/bin/perl\r e tenta executar um binário com carriage return no nome. Resultado: No such file or directory ou Exec format error, dependendo do caso.
A documentação da cPanel é explícita quanto a isso ao orientar o envio de scripts Perl em modo ASCII pelo cliente FTP. Quem usa SFTP ou Git na tubulação não converte nada automaticamente, então a responsabilidade volta para o editor e para a configuração do repositório.
Detectar e corrigir:
# o 'file' diz na cara: "with CRLF line terminators"
file ~/public_html/cgi-bin/contato.cgi
# ver o ^M na primeira linha
cat -A ~/public_html/cgi-bin/contato.cgi | head -1
# corrigir (preferencial, se existir no servidor)
dos2unix ~/public_html/cgi-bin/contato.cgi
# alternativa sem dos2unix
sed -i 's/\r$//' ~/public_html/cgi-bin/contato.cgi
Faça cópia antes do sed -i. Ele altera o arquivo no lugar e não pergunta nada.
Pasta sem ExecCGI, ou handler não aplicado àquela extensão
O script pode estar impecável e ainda assim não rodar, porque a pasta onde ele mora não tem execução de CGI habilitada, ou porque a extensão não está associada ao handler naquele ponto da árvore. Os sintomas são dois e bem distintos: o navegador mostra o código-fonte em texto puro (handler ausente) ou devolve 403/500 com menção a ExecCGI no log.
Há ainda um 500 que não é do script: .htaccess com Options +ExecCGI em servidor que não permite aquele override gera Option ExecCGI not allowed here e derruba a pasta inteira, inclusive páginas que nada têm com CGI. Se o 500 começou a valer para tudo abaixo de um diretório, olhe o .htaccess antes de olhar o script.
Teste de eliminação que resolve a dúvida em um minuto: copie o script para cgi-bin (o diretório que o cPanel já entrega habilitado), ajuste a permissão para 755 e chame pela URL. Se funcionar lá e não na pasta original, a causa é de configuração de diretório, não do código.
Quando não é nenhuma das quatro: CGI.pm fora do núcleo e cabeçalho faltando
Duas sobras aparecem com frequência depois de migração para Perl mais novo:
Can't locate CGI.pm in @INC: o móduloCGIsaiu do núcleo do Perl e precisa ser instalado na conta. Em cPanel, pelo gerenciador de módulos Perl da própria conta.Premature end of script headerscom o script rodando bem no shell: falta o cabeçalho. Todo CGI precisa imprimirContent-Type: text/htmlseguido de uma linha em branco antes de qualquer HTML. Sem a linha em branco, o Apache considera que a saída terminou antes dos cabeçalhos.
O teste direto separa os dois casos:
cd ~/public_html/cgi-bin
perl -cw contato.cgi # "syntax OK" ou o erro de compilação com número da linha
./contato.cgi | head -5 # a primeira linha precisa ser o Content-Type
Como auditar trinta sites antes da próxima migração quebrar um deles
O que interessa para quem mantém trinta sites não é resolver um formulário, é descobrir quais dos trinta vão quebrar na próxima migração. Rode por conta, com SSH, e leve o resultado para a planilha de manutenção.
Inventariar os scripts com permissão e dono na mesma saída
find ~/public_html -type f \( -name '*.cgi' -o -name '*.pl' \) \
-printf '%m %u:%g %p\n'
Saída em três colunas: permissão octal, dono:grupo, caminho. Tudo que não for 755 na primeira coluna, ou tiver dono diferente do usuário da conta na segunda, entra na lista de correção.
Achar os arquivos que chegaram com CRLF
grep -rl $'\r' ~/public_html --include='*.cgi' --include='*.pl'
Cada caminho listado tem carriage return em alguma linha. Confirme com file antes de converter, para não mexer em arquivo que tem \r dentro de uma string por motivo legítimo.
Conferir todos os shebangs do site de uma vez
find ~/public_html -type f \( -name '*.cgi' -o -name '*.pl' \) \
-exec head -1 {} \; | sort | uniq -c | sort -rn
Você recebe a contagem de cada shebang distinto usado no site. Compare com o which perl do servidor. Em site herdado, é comum aparecerem três variações diferentes no mesmo domínio.
Validar a sintaxe sem executar, e por que perl -c não é inerte
find ~/public_html -type f \( -name '*.cgi' -o -name '*.pl' \) \
-exec perl -cw {} \; 2>&1 | grep -v 'syntax OK'
Sobra só o que não compila. Módulo faltando também aparece aqui, como Can't locate ... in @INC.
Uma ressalva antes de sair rodando isso em script de terceiro: perl -c não é inerte. Ele compila, e compilar significa executar blocos BEGIN e resolver os use, que por sua vez podem ter BEGIN próprios. Em código herdado de origem desconhecida, leia o cabeçalho do arquivo antes ou faça a checagem em uma conta de teste, não na produção do cliente.
Testar pela rede cada script publicado com curl
Sintaxe boa no shell não garante resposta HTTP correta, porque o ambiente do suEXEC é diferente do seu shell. Feche a auditoria com uma chamada real por script publicado:
for u in /cgi-bin/contato.cgi /cgi-bin/busca.cgi; do
printf '%s ' "$u"
curl -s -o /dev/null -w '%{http_code}\n' "https://exemplo.com.br$u"
done
Os caminhos acima são exemplo. Substitua pelos do site auditado.
Registrar quatro campos por domínio para orçar a correção em bloco
Para cada domínio, anote quatro campos: quantidade de scripts CGI, permissões fora do padrão, arquivos com CRLF, shebangs divergentes. Com essa tabela em mãos, você sabe de antemão quais clientes precisam de aviso antes de uma mudança de servidor, e consegue orçar a correção em bloco em vez de apagar incêndio um a um.
Como padronizar para não reincidir
- Modo de transferência: configure o cliente FTP para enviar
.cgi,.ple.cgi.tplem ASCII, ou pare de usar FTP para esses arquivos. A cPanel documenta o modo de upload como causa de falha em script Perl, e é a única das quatro que você reintroduz sozinho toda vez que edita o arquivo no Windows. - Editor e repositório: force final de linha LF no editor e no
.gitattributesdo projeto para as extensões de script. Isso resolve o problema na origem, não no servidor. - Permissão como padrão de deploy: 755 para script e para a pasta que o contém. Nunca 777. Se algo só funciona com 777, o problema é dono, não permissão.
- Um teste de fumaça por site: guarde no repositório da agência o loop de
curldo passo 5, com as URLs reais de cada cliente. Rodar depois de qualquer migração custa segundos. - Decisão de fim de vida: se o formulário CGI é um script de 2004 sem manutenção, o conserto é paliativo. Vale precificar a substituição por um formulário no CMS que o cliente já usa, com destino de e-mail autenticado. Diga isso ao cliente com o orçamento das duas opções lado a lado, em vez de consertar de graça a cada migração.
O que dizer ao cliente que jura que ninguém mexeu no formulário
A pergunta que sempre vem é "mas ninguém mexeu nisso". Use uma versão desta resposta, que é verdadeira e não joga culpa em ninguém:
Se for o caso de dono de arquivo errado, acrescente que a correção depende de um ajuste com acesso administrativo ao servidor, que você já solicitou. Cliente aceita bem prazo com causa nomeada. O que ele não aceita é "estamos investigando".
O que este artigo não mede
Não há medição de laboratório aqui. Nenhum número deste texto vem de teste próprio: o conteúdo se apoia na documentação oficial da cPanel para troubleshooting de Perl e CGI, no comportamento documentado do suEXEC e no que as mensagens do Apache significam. Também não há estatística de prevalência: quando o texto fala em "as quatro causas", está listando as verificações que a documentação coloca em primeiro lugar, não uma contagem de casos reais. Os caminhos de arquivo, nomes de script e domínios usados nos comandos são exemplos, e as mensagens de log podem variar em texto exato conforme a versão do Apache e do suexec instalada no seu servidor.
O que vale replicar é o método: pegar a linha literal do log, casar com a família de mensagem da tabela, testar a hipótese com um comando e validar com um curl. Quatro causas, quatro verificações, sem chute.
Fonte: cPanel, Troubleshooting Guide for Perl and CGI Scripts, consultada em 28/09/2026.
Referências
- Documentação oficial (cpanel) — Troubleshooting Guide for Perl and CGI Scripts. Consultado em 2026-09-28.