blog
Painéis

Sistema pede ionCube Loader e não abre: 4 passos no cPanel

A caixinha marcada na versão errada de PHP não muda nada na tela, e é isso que faz o dono do site abrir o chamado errado. Este guia mostra como descobrir a versão certa, ligar o loader e provar que funcionou.

JR · · 11 min de leitura · 2 tabelas · 6 blocos de código

Resposta curta: são 4 passos no cPanel, e o que resolve a tela branca é marcar o ionCube Loader na mesma versão de PHP que aquele endereço usa de verdade, não na versão padrão da conta. Confirme com uma página phpinfo temporária e apague depois.

Neste artigo
  1. Tela branca ou aviso em inglês: o que o servidor está dizendo
  2. Versão do PHP e lista de extensões são duas configurações separadas
  3. O que separar antes de abrir o cPanel
  4. Como ativar o ionCube Loader no cPanel em 4 passos
  5. Quando o ioncube_loader não aparece na lista daquela versão
  6. O que cada mensagem de erro significa e o que fazer
  7. Frases prontas para o chamado na hospedagem e no fornecedor
  8. Quem resolve cada parte, da hospedagem ao fornecedor do sistema
  9. Três coisas para não esquecer

Tela branca ou aviso em inglês: o que o servidor está dizendo

O cliente abre o endereço e vê uma tela branca. Ou vê uma frase em inglês parecida com esta: Site error: the file /home/.../index.php requires the ionCube PHP Loader ... to be installed by the site administrator.

No negócio, isso significa uma coisa só: ninguém entra. O sistema de pedidos não carrega, o painel do cliente não abre, o orçamento não é enviado. E como a tela continua exatamente igual depois de você mexer no painel, a sensação é de que o problema é outro, quando na maioria das vezes é a mesma coisa marcada no lugar errado.

O ionCube é um cadeado. Muitos sistemas comerciais (ERP, que é o sistema de gestão da empresa, sistema de agendamento, painel de revenda, plugin pago) são entregues com o código embaralhado para ninguém copiar. Para o servidor conseguir ler esse código embaralhado, precisa existir uma peça chamada ionCube Loader ligada no servidor. Se ela não está ligada, o sistema não roda. Não tem meio termo, não tem site lento: ou abre, ou não abre.

Você não precisa entender como o ionCube funciona por dentro. Precisa entender onde ele é ligado, e esse é o ponto onde quase todo mundo erra.

Versão do PHP e lista de extensões são duas configurações separadas

Dentro da sua hospedagem existem duas configurações separadas, e elas são independentes:

  1. A versão do PHP que aquele endereço usa. PHP é o motor que roda o site. Ele tem versões, como um carro tem ano de fabricação: 7.4, 8.0, 8.1, 8.2 e assim por diante. Cada domínio, subdomínio e às vezes cada pasta pode estar rodando uma versão diferente.
  2. A lista de extensões daquela versão. Extensão é um acessório do motor. O ionCube Loader é uma dessas extensões. A documentação do cPanel (cPanel é o painel de controle da hospedagem, a tela com ícones onde você administra site, arquivos e e-mail) trata o carregamento do ionCube como uma opção da interface de opções do PHP, ligada por versão (docs.cpanel.net).

A armadilha: cada versão de PHP tem a sua própria lista de extensões. Se o seu sistema roda em PHP 8.2 e você marca o ionCube na lista do PHP 8.1, o painel vai dizer que salvou, vai mostrar a caixinha marcada, e a tela branca vai continuar igualzinha. Nada de errado aconteceu. Você ligou o acessório em um motor que não é o que está puxando o carro.

E tem um agravante comum: a raiz e a subpasta podem rodar versões diferentes. O site institucional em seusite.com.br pode estar em uma versão, e o sistema em seusite.com.br/sistema ou em app.seusite.com.br em outra. Por isso a primeira coisa a fazer não é marcar nada. É descobrir a versão daquele endereço específico que está dando erro.

O que separar antes de abrir o cPanel

Separe isto antes de abrir o painel:

O procedimento abaixo é todo feito por cliques, em duas telas do cPanel. Não precisa de terminal, não precisa de programador para executar, e é reversível: desmarcar a extensão devolve o estado anterior.

Como ativar o ionCube Loader no cPanel em 4 passos

Passo 1: descubra a versão de PHP que a pasta do erro realmente usa

A forma mais confiável, e que funciona também para subpasta e subdomínio, é publicar uma página de conferência temporária dentro da pasta daquele endereço.

  1. Entre no cPanel e abra o Gerenciador de Arquivos (File Manager).
  2. Navegue até a pasta do endereço com erro:
  1. Clique em + Arquivo (ou "Novo arquivo"), dê um nome difícil de adivinhar terminando em .php, por exemplo checagem-4821.php, e confirme.
  2. Com o arquivo selecionado, clique em Editar (Edit), cole exatamente as duas linhas abaixo e clique em Salvar.
<?php
phpinfo();
  1. No navegador, abra https://seusite.com.br/sistema/checagem-4821.php (troque pelo seu endereço e pelo nome que você deu ao arquivo). Se o caso for subdomínio, o endereço fica https://app.seusite.com.br/checagem-4821.php.

Resultado esperado: uma página cheia de tabelas azuis e cinzas. No topo, em letras grandes, aparece algo como PHP Version 8.2.14. Anote esses dois primeiros números, por exemplo 8.2. Essa é a versão que manda naquela pasta.

Aproveite e já confira se o ionCube não está ligado: pressione Ctrl + F (no Mac, Cmd + F), digite ionCube e veja se aparece algo. Se aparecer um bloco com o nome ionCube, ou uma linha no topo mencionando o ionCube PHP Loader, a extensão já está ativa e o seu problema é outro (provavelmente licença). Nesse caso, faça primeiro o Passo 4 e apague a página de conferência, e só depois vá para a seção de erros comuns. Não deixe essa página publicada no site em nenhuma hipótese.

Se der erro 404 (404 é a página de "endereço não encontrado"): você criou o arquivo na pasta errada, ou digitou o nome diferente. Confira o caminho na tela de Domínios e no Gerenciador de Arquivos.

Se a página baixar como arquivo em vez de abrir: aquele endereço não está processando PHP naquela pasta. Anote isso, apague a página de conferência seguindo o Passo 4 e leve o caso ao suporte, é um problema distinto.

Passo 2: marque o ioncube_loader nessa versão sem mexer no padrão da conta

  1. Volte ao cPanel e abra Selecionar versão do PHP (Select PHP Version).
  2. No alto da tela existe um seletor com a versão do PHP e, abaixo, uma lista de extensões com caixinhas.
  3. Confirme que o seletor está na mesma versão que você anotou no passo 1. Se você anotou 8.2, o seletor precisa estar em 8.2. Se estiver em outra, pare e leia o aviso logo abaixo.
  4. Na lista de extensões, procure por ioncube_loader (a lista costuma estar em ordem alfabética, então ele fica perto de imap e intl). Marque a caixinha.
  5. Clique em Salvar ou Aplicar. Dependendo da versão do painel, a extensão é aplicada assim que você marca, mas confirme que a tela avisou que a alteração foi gravada.

Aviso importante sobre o seletor de versão: em muitos painéis, mudar a versão nesse seletor muda a versão padrão da conta inteira, e não só a do site com problema. Se a versão mostrada ali for diferente da que você anotou no passo 1, não force. Abra um chamado com a frase pronta que está na seção de frases prontas e peça para o suporte habilitar o loader na versão específica daquele domínio. Leva o mesmo tempo e não derruba os outros sites da conta. Se você parar o procedimento aqui para abrir o chamado, apague antes a página de conferência (Passo 4): o suporte consegue conferir o phpinfo pelo próprio servidor, sem que ela fique exposta na internet.

Passo 3: confirme no phpinfo que o loader carregou

  1. Volte ao endereço da sua página de conferência, por exemplo https://seusite.com.br/sistema/checagem-4821.php.
  2. Atualize forçando a limpeza do cache: Ctrl + F5 no Windows, Cmd + Shift + R no Mac. Ou abra em uma janela anônima.
  3. Procure por ionCube com Ctrl + F.

Resultado esperado: aparece uma seção com o nome ionCube, e/ou uma linha no bloco chamado Zend (Zend é o motor interno do PHP, esse nome aparece escrito no relatório) mencionando o ionCube PHP Loader. Confirme também que a versão do PHP no topo continua sendo a mesma que você configurou.

Se não aparecer nada: a caixinha foi marcada em outra versão, ou a alteração não chegou a ser salva. Repita o passo 2 conferindo o seletor de versão.

  1. Agora abra o endereço real do sistema. Se ele carregar, a parte do loader está resolvida. Mesmo assim, não encerre aqui: falta o Passo 4.

Passo 4: apague a página de conferência e esvazie a lixeira

Esse passo não é opcional, e vale para qualquer caminho que você tenha seguido acima, inclusive quando o problema acabou sendo outro. A página phpinfo mostra detalhes da configuração do servidor que não interessam a estranhos.

  1. Volte ao Gerenciador de Arquivos, entre na pasta, selecione o arquivo checagem-4821.php.
  2. Clique em Excluir (Delete).
  3. Esvazie a Lixeira (Trash) do Gerenciador de Arquivos, porque o arquivo excluído costuma ficar lá.
  4. Abra o endereço da página no navegador de novo. O esperado agora é erro 404, ou seja, endereço não encontrado.
Os 4 passos no cPanel, do erro ao site no arDescobrir a versãophpinfo dentro da pasta do erroMarcar o loaderioncube_loader naquela versão de PHPConferirionCube aparece no phpinfoApagar a páginaExcluir arquivo e esvaziar lixeira
Os quatro passos do procedimento, todos por clique no cPanel. O passo 4 vale para qualquer cenário, inclusive quando a causa era outra.

Quando o ioncube_loader não aparece na lista daquela versão

Acontece de o ioncube_loader simplesmente não aparecer na lista de extensões de uma versão de PHP. Isso normalmente significa que ainda não existe loader publicado para aquela versão, ou que ele não está disponível naquele servidor.

A reação errada é insistir: procurar arquivo solto na internet, pedir instalação manual, tentar carregar por arquivo de configuração. Isso costuma gerar erro 500 (a página de erro do servidor: em vez do site, o visitante vê um aviso de falha e o site fica fora do ar) e mais tempo de prejuízo.

A reação certa é inverter o problema. O ionCube é um requisito do sistema que você comprou, e todo fornecedor desse tipo de sistema documenta em quais versões de PHP ele roda. Então:

  1. Pergunte ao fornecedor do sistema em quais versões de PHP ele é homologado.
  2. Pergunte ao suporte da hospedagem em quais dessas versões o loader está disponível.
  3. Coloque o site na versão que aparece nas duas listas, e marque o ionCube nessa versão.

Voltar o site para uma versão um pouco mais antiga, porém suportada, resolve hoje. Brigar com a extensão pode não resolver nunca. Faça a troca de versão fora do horário comercial e tenha um backup recente antes, porque versão mais antiga de PHP pode quebrar outras partes do site.

O que cada mensagem de erro significa e o que fazer

O que você vê Causa provável O que fazer
Marquei a caixinha e a tela continua idêntica O ionCube foi ligado em uma versão de PHP diferente da que a pasta usa Refaça o passo 1, anote a versão real daquele endereço e marque nela
A caixinha aparece desmarcada quando volto na tela A alteração não foi salva, ou o botão Aplicar não chegou a ser clicado Marque de novo, clique em salvar e recarregue a página do painel para confirmar
Continua a tela antiga mesmo depois de tudo certo Cache do navegador servindo a página velha Atualize com Ctrl + F5 ou teste em janela anônima e em outro aparelho, como o celular na rede móvel
A raiz do site abre, mas a subpasta ou o subdomínio não Raiz, subpasta e subdomínio rodam versões diferentes de PHP Descubra a pasta daquele endereço em Domínios, publique a página de conferência lá dentro, trate aquela versão e apague a página depois
A mensagem agora fala em licença, arquivo de licença expirado ou não encontrado O loader está carregado, o problema é a licença do sistema comercial Fale com quem vendeu o sistema. Isso não se resolve na hospedagem
A mensagem pede uma versão mais nova do loader O arquivo do sistema foi gerado para um loader mais recente Peça ao fornecedor a versão compatível, ou peça ao suporte a atualização do loader
Depois de trocar a versão do PHP, o site virou erro 500 (site fora do ar, com página de erro do servidor) Alguma outra parte do site não roda naquela versão Volte a versão anterior no painel e trate o requisito com o desenvolvedor

A linha da licença é a que mais confunde. Depois que o loader passa a funcionar, a mensagem na tela muda. Se antes falava em loader ausente e agora fala em licença, você resolveu a sua parte. Guarde o texto exato da nova mensagem, ele é a prova de que a hospedagem está correta.

Frases prontas para o chamado na hospedagem e no fornecedor

Copie, troque o que está entre colchetes e cole. Chamado com endereço, versão e pedido claro costuma voltar resolvido na primeira resposta.

Para o suporte da hospedagem, quando você não conseguiu marcar sozinho:

Meu sistema exige o ionCube Loader para funcionar.
O endereco com erro e: https://[seusite.com.br/sistema/]
Conferi por phpinfo e essa pasta roda PHP [8.2].
Por favor, habilitem o ionCube Loader nessa versao de PHP,
para esse dominio especifico, e me confirmem que ele aparece
carregado em phpinfo. Ha outros sites nesta conta, entao peco
que nao alterem a versao padrao dos demais.

Para o suporte, quando o loader não existe para a versão atual:

O endereco https://[seusite.com.br/sistema/] roda PHP [8.3]
e o ioncube_loader nao aparece na lista de extensoes dessa versao.
Em quais versoes de PHP o loader esta disponivel no servidor?
Pretendo mover apenas esse dominio para uma versao suportada.

Para o suporte, quando você não acha a pasta do subdomínio:

Preciso saber qual e a pasta (raiz do documento) e a versao de PHP
do endereco https://[app.seusite.com.br]. Ele esta apresentando erro
de ionCube Loader ausente e quero tratar so esse endereco,
sem mexer nos outros sites da conta.

Para o desenvolvedor ou para o fornecedor do sistema:

O ionCube Loader ja esta carregado no servidor, confirmei por phpinfo
na versao PHP [8.2], que e a versao usada pela pasta do sistema.
A mensagem que aparece agora e exatamente esta: [cole a mensagem].
Preciso saber se e licenca, versao do loader ou configuracao do sistema.

Para registrar o que foi feito, no mesmo chamado:

Ja executei: identifiquei a versao de PHP da pasta por phpinfo,
marquei o ioncube_loader nessa versao em Selecionar versao do PHP,
testei com cache limpo e em janela anonima, e apaguei a pagina de teste.

Quem resolve cada parte, da hospedagem ao fornecedor do sistema

Antes de cobrar a pessoa errada, vale separar as responsabilidades. Isso economiza dias de ida e volta.

Sintoma Responsável Por quê
Loader não está ligado na versão do domínio Você no cPanel, ou o suporte da hospedagem É configuração da conta de hospedagem, por versão de PHP
Loader não existe para a versão desejada Hospedagem informa, você decide a versão Depende do que está instalado no servidor e do que o sistema aceita
Licença do sistema vencida ou inválida Fornecedor do sistema A licença é do software, não da hospedagem
Arquivo codificado exige loader mais novo Fornecedor do sistema, com apoio da hospedagem Compatibilidade entre o codificador e o loader instalado
Site quebra depois de trocar a versão do PHP Desenvolvedor do site É código do site que não roda naquela versão
Qual mensagem leva a qual responsávelTela branca ou erro de loaderComece pela versão de PHP da pastaLoader não aparece na listaHospedagem informa versões disponíveisMensagem mudou para licençaFornecedor do sistema resolvePede loader mais novoFornecedor, com apoio da hospedagemSite quebrou após trocar versãoDesenvolvedor do site
Use a mensagem que aparece na tela para saber a quem abrir o chamado antes de cobrar a pessoa errada.

Três coisas para não esquecer

Três coisas. A primeira é que a caixinha do ionCube só tem efeito na versão de PHP que aquele endereço realmente usa, e a única forma de ter certeza dessa versão é olhar o phpinfo publicado dentro da pasta daquele endereço, que no caso de subdomínio você confirma na tela de Domínios do cPanel. A segunda é que, depois de ligado, a tela precisa mudar de mensagem: se mudou, a parte da hospedagem está feita e a bola passou para quem vendeu o sistema. A terceira é que a página de conferência sai do ar no fim, em qualquer cenário, mesmo quando a causa acabou sendo outra.

Referência de documentação usada neste guia: PHP Options: ionCube Loader, documentação oficial do cPanel.

Referências

  1. Documentação oficial (cpanel) — PHP Options: ionCube Loader. Consultado em 2026-09-28.
Leia também