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

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

João Rizzon · 2026-09-29 · Infraestrutura web

---

## 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 um `error_log` solto dentro de `public_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](https://docs.cpanel.net/knowledge-base/scripts-and-utilities/troubleshooting-guide-for-perl-and-cgi-scripts/) 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:

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

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

```bash
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:

```bash
# 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ódulo `CGI` saiu 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 headers` com o script rodando bem no shell: falta o cabeçalho. Todo CGI precisa imprimir `Content-Type: text/html` seguido 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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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`, `.pl` e `.cgi.tpl` em 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 `.gitattributes` do 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 `curl` do 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:

> **** O formulário não mudou. O servidor onde ele roda foi atualizado e passou a exigir dele três coisas que antes eram toleradas: permissão exata de arquivo, caminho correto do interpretador e quebra de linha no padrão do sistema. O código continua o mesmo, o ambiente ao redor ficou mais rígido, por segurança. A correção é de configuração e eu já identifiquei qual das causas é, pela mensagem que o servidor registrou no log.

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](https://docs.cpanel.net/knowledge-base/scripts-and-utilities/troubleshooting-guide-for-perl-and-cgi-scripts/), consultada em 28/09/2026.

