blog
Infraestrutura web

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.

JR · · 12 min de leitura · 1 tabela · 10 blocos de código

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
  1. Por que um CGI parado há dez anos volta a dar 500 sem ninguém tocar nele
  2. Onde está o log certo (e por que o log do PHP não serve aqui)
  3. Que causa cada família de mensagem do error_log aponta
  4. As quatro causas e a verificação que confirma cada uma
  5. Como auditar trinta sites antes da próxima migração quebrar um deles
  6. Como padronizar para não reincidir
  7. O que dizer ao cliente que jura que ninguém mexeu no formulário
  8. 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:

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.

Do log ate a causa confirmadaReproduzir com curltail -f no log do dominioCopiar a linha literalGuardar o trecho da mensagemCasar com a familiaexec of, headers, suexec, ExecCGITestar a hipoteseUm comando por causaValidar pela redecurl devolve 200
Mesmo metodo para qualquer das quatro causas: log, hipotese, comando, validacao.

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:

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.

Auditoria de CGI em carteira de sitesInventariofind com permissao e donoCRLFgrep por carriage returnShebangshead -1 agrupado por contagemSintaxeperl -cw fora da producaoTeste de fumacacurl em cada URL publicada
Ordem da auditoria em carteira: cada etapa alimenta uma coluna da planilha.

Como padronizar para não reincidir

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

  1. Documentação oficial (cpanel) — Troubleshooting Guide for Perl and CGI Scripts. Consultado em 2026-09-28.
Leia também