Como resolver failed to open stream em Mail.php no cPanel
Como ler o include_path do log, instalar o pacote certo pelo cPanel na versão de PHP correta e saber quando o problema é Composer, não PEAR.

Resposta curta: O erro `failed to open stream` em `Mail.php` significa que o pacote PEAR Mail não está instalado na sua conta ou não está no `include_path`. Instale pelo PHP PEAR Packages do cPanel, na mesma versão de PHP do domínio, junto com Net_SMTP e Net_Socket, e confirme com `stream_resolve_include_path('Mail.php')`.
Neste artigo
A linha do log que importa
O erro chega quase sempre assim, dentro de error_log na pasta do site ou no Log de Erros do cPanel:
PHP Warning: require_once(Mail.php): failed to open stream:
No such file or directory in /home/usuario/public_html/envio.php on line 3
PHP Fatal error: Uncaught Error: Failed opening required 'Mail.php'
(include_path='.:/usr/share/pear')
Três informações estão ali, e elas resolvem o caso:
- O arquivo procurado:
Mail.php. Não é o seu arquivo, é uma biblioteca. - Quem procurou:
/home/usuario/public_html/envio.php, linha 3. - Onde procurou: o
include_path. Tudo que aparece entre as aspas é a lista de pastas que o PHP varreu. Se o arquivo não está em nenhuma delas, o PHP para.
Mail.php é o ponto de entrada do pacote Mail do PEAR, o repositório antigo de bibliotecas PHP. Código que usa require_once 'Mail.php'; e depois Mail::factory('smtp', ...) espera esse pacote instalado na conta. Se o site veio de um servidor onde alguém instalou PEAR e migrou para outro onde ninguém instalou, o arquivo simplesmente não existe ali.
O mesmo raciocínio vale para os parentes: Mail/mime.php é o pacote Mail_Mime, Net/SMTP.php é o Net_SMTP, HTTP/Request2.php é o HTTP_Request2.
Do nome do arquivo ao nome do pacote
A tradução é quase mecânica: o caminho que aparece no erro, sem o .php e com as barras viradas em sublinhado, costuma ser o nome do pacote PEAR.
| Linha no erro | Pacote PEAR a instalar |
|---|---|
require_once 'Mail.php' |
|
require_once 'Mail/mime.php' |
Mail_Mime |
require_once 'Net/SMTP.php' |
Net_SMTP |
require_once 'Net/Socket.php' |
Net_Socket |
require_once 'HTTP/Request2.php' |
HTTP_Request2 |
require_once 'DB.php' |
DB |
Um detalhe que economiza uma segunda rodada de erro: o pacote Mail sozinho raramente basta. Quando você usa Mail::factory('smtp', ...), ele chama o Net_SMTP, que chama o Net_Socket. Se instalar só o Mail, o próximo log vai dizer Net/SMTP.php: failed to open stream. Já conte com os três.
Instalar pelo PHP PEAR Packages do cPanel
O cPanel tem uma interface própria para isso, descrita na documentação oficial do PHP PEAR Packages. Ela instala o pacote na sua conta, não no servidor inteiro, então você não depende de ninguém para liberar.
1. Descobrir qual versão de PHP o site usa
Faça isto antes, porque instalar o pacote na versão errada é o jeito mais comum de "instalei e continua dando erro". No cPanel, seção Software, abra MultiPHP Manager: é lá que cada domínio aparece com a versão de PHP que usa. Anote a versão ativa do domínio: 8.1, 8.2, 8.3, o que for. Guarde essa informação, porque a edição de diretivas acontece em outra tela, Select PHP Version (em contas sem ela, MultiPHP INI Editor), que é onde fica a aba de opções com o include_path.
2. Abrir o PHP PEAR Packages
No cPanel, seção Software, clique em PHP PEAR Packages. A tela tem uma caixa de busca de módulos e uma lista dos pacotes já instalados.
3. Procurar e instalar
Digite Mail na caixa Search e clique em Go. A busca devolve os pacotes com nome parecido. Clique em Install na linha do pacote exato que você quer. Repita para Net_SMTP e Net_Socket.
A saída da instalação aparece na própria tela. Leia até o fim: ela mostra as pastas onde os arquivos foram gravados. Guarde esse caminho, você vai precisar dele no passo seguinte.
4. Anotar o caminho da sua pasta PEAR
A interface mostra o caminho da instalação local da conta, normalmente algo como /home/usuario/php. O valor exato aparece na própria tela do PHP PEAR Packages e na saída da instalação. Copie exatamente o que estiver ali em vez de supor.
Se o cPanel instalou mas o PHP continua não achando, é porque esse caminho não está no include_path. É o que o próximo passo resolve.
Fazer o PHP enxergar a pasta
Há duas formas. Comece pela primeira. A busca e a instalação de pacotes da seção anterior estão descritas na documentação do cPanel; a edição de include_path a seguir não está nela, é o procedimento comum da interface e pode variar conforme a configuração do servidor.
Pelo painel, sem tocar em arquivo
Abra Select PHP Version, aba Options. Procure a diretiva include_path. O valor atual costuma ser .:/usr/share/pear. Acrescente, separado por dois-pontos, o caminho que você anotou. Exemplo (é um exemplo, use o caminho da sua tela):
.:/usr/share/pear:/home/usuario/php
Salve. A mudança vale para todos os sites naquela versão de PHP, o que normalmente é o que você quer.
Pelo próprio código, quando o painel não deixa
Se a diretiva estiver travada, dá para resolver no topo do script que falha, antes do require_once:
<?php
set_include_path(get_include_path() . PATH_SEPARATOR . '/home/usuario/php');
require_once 'Mail.php';
Linha a linha: get_include_path() lê a lista atual, PATH_SEPARATOR é o separador correto do sistema, e set_include_path() grava a lista com a sua pasta no fim. Só então o require_once é executado. Funciona, mas precisa ser repetido em cada ponto de entrada da aplicação, por isso é o plano B.
Confirmar que funcionou
Não confie na mensagem de sucesso da instalação. Teste do jeito que o PHP vai testar.
Crie um arquivo teste-pear.php em public_html com este conteúdo:
<?php
echo 'include_path: ' . get_include_path() . "\n";
$arquivo = stream_resolve_include_path('Mail.php');
echo $arquivo ? "Encontrado em: $arquivo\n" : "NAO encontrado\n";
Abra https://seudominio.com.br/teste-pear.php no navegador. O resultado esperado é a lista de pastas, já com a sua, e uma linha Encontrado em: seguida do caminho completo do Mail.php. Se vier NAO encontrado, o caminho que você acrescentou está errado ou o pacote foi instalado em outra versão de PHP.
Um aviso que vale o parágrafo: apague esse arquivo depois do teste. Vale ainda mais se você usar phpinfo(), que expõe caminhos e configurações do servidor para qualquer visitante.
Se o site roda por CLI ou cron, teste também pelo terminal. O PHP de linha de comando pode usar outro php.ini e, em servidores cPanel, o php do shell costuma ser até uma versão diferente da que o site usa:
php -r "echo stream_resolve_include_path('Mail.php') ?: 'nao achou';"
A saída esperada é o caminho completo do arquivo, algo como /home/usuario/php/Mail.php. Se aparecer nao achou, ou o pacote não está no include_path do CLI, ou você testou com outra versão de PHP. Para chamar a mesma versão do site, troque php pelo binário correspondente, por exemplo ea-php82 -r "..." para PHP 8.2. Confirme a versão em uso com php -v antes de concluir qualquer coisa.
Quando PEAR é a resposta errada
Antes de instalar qualquer coisa, abra o arquivo que gerou o erro e olhe o que ele pede.
- Se a linha é
require_once 'Mail.php';e o código chamaMail::factory(...), é PEAR. Siga os passos acima. - Se existe uma pasta
vendor/no projeto, ou o código temrequire __DIR__ . '/vendor/autoload.php';, não é PEAR. É Composer, e o erro quase sempre significa que a pastavendornão foi enviada no deploy ou foi excluída. Instalar PEAR não resolve e ainda deixa biblioteca duplicada na conta. - Se o projeto usa PHPMailer, Symfony Mailer ou Laravel, é Composer. PHPMailer moderno não se carrega com
require_once 'Mail.php'.
O pacote Mail do PEAR é código antigo e com manutenção mínima. Ele continua funcionando para scripts legados, e instalar é legítimo quando você precisa que o site volte hoje. Mas se o script é seu e você tem como mexer, migrar o envio para PHPMailer via Composer é o caminho que não vai te trazer de volta a esta página em dois anos.
Como voltar atrás
Tudo aqui é reversível, desde que você faça o básico:
- Antes de editar o arquivo PHP, faça uma cópia de verdade: no Gerenciador de Arquivos do cPanel, selecione o arquivo e use Download para baixar uma cópia, ou use Copy e salve como
envio.php.bakna mesma pasta. O editor do painel não guarda versão anterior: depois que você salva, o conteúdo antigo se perde. - Antes de mudar
include_path, copie o valor atual para um bloco de notas. Se algo quebrar, cole de volta e salve. - Para remover um pacote, volte em PHP PEAR Packages e use Uninstall na linha dele, conforme a interface descrita na documentação do cPanel.
Checklist de diagnóstico
Quando o erro insiste, percorra nesta ordem.
| Sintoma | Causa provável | O que fazer |
|---|---|---|
Mail.php: failed to open stream |
Pacote Mail não instalado | Instalar Mail no PHP PEAR Packages |
| Instalou, mas o erro continua igual | Pacote em outra versão de PHP | Conferir a versão do domínio no MultiPHP Manager e reinstalar |
Net/SMTP.php: failed to open stream |
Dependência faltando | Instalar Net_SMTP e Net_Socket |
| Funciona no navegador, falha no cron | PHP CLI com php.ini diferente |
Testar com php -r e ajustar o include no script |
Erro cita vendor/autoload.php |
Projeto é Composer, não PEAR | Reenviar a pasta vendor ou rodar a instalação de dependências |
| Nada aparece no log | Log do PHP em outro lugar | Abrir Errors/Log de Erros no cPanel e checar a pasta do domínio |
A regra geral vale para qualquer failed to open stream, não só para o Mail.php: o PHP está dizendo exatamente qual arquivo procurou e em quais pastas. Resolver é colocar o arquivo em uma dessas pastas, ou colocar a pasta na lista. Não há terceiro caminho.
Referências
- Documentação oficial (cpanel) — PHP PEAR Packages. Consultado em 2026-10-08.