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

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

João Rizzon · 2026-09-29 · Painéis

---

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

- **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.
- **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](https://docs.cpanel.net/ea4/php/php-options-php-loader-ioncube6/)).

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:

- **Acesso ao cPanel** (usuário e senha). Se quem fez o site não te passou, peça ao suporte da hospedagem: o acesso é seu, é da conta que você paga.
- **O endereço exato que dá erro.** Não "meu site". Algo como `https://seusite.com.br/sistema/`. É esse endereço que manda na resposta.
- **O nome do sistema que exige o ionCube** e o contato de quem vendeu ou instalou. Você vai precisar dele se o problema for de licença.
- **Saber se outros sites estão na mesma conta.** Se sim, leia o aviso sobre o seletor de versão, no fim do Passo 2, antes de trocar qualquer versão de PHP: mexer na versão padrão da conta pode afetar os vizinhos.

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.

- Entre no cPanel e abra o **Gerenciador de Arquivos** (File Manager).
- Navegue até a pasta do endereço com erro:

- **Site principal** (`seusite.com.br`): costuma ser `public_html`.
- **Subpasta** (`seusite.com.br/sistema`): é `public_html/sistema`.
- **Subdomínio** (`app.seusite.com.br`): costuma ser `public_html/app`, ou seja, uma pasta com o nome do subdomínio. Nem sempre é assim, então confira: no cPanel, abra **Domínios** (Domains) ou **Subdomínios** (Subdomains). A lista mostra cada endereço com o caminho da sua pasta, chamado de **raiz do documento** (document root). É esse caminho que vale.
- **Não sabe em qual dos três casos você está?** Use a tela de Domínios do cPanel: procure na lista o endereço exato que dá erro e use o caminho que aparece ao lado dele.

- Clique em **+ Arquivo** (ou "Novo arquivo"), dê um nome difícil de adivinhar terminando em `.php`, por exemplo `checagem-4821.php`, e confirme.
- Com o arquivo selecionado, clique em **Editar** (Edit), cole exatamente as duas linhas abaixo e clique em **Salvar**.

```php
<?php
phpinfo();
```

- 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

- Volte ao cPanel e abra **Selecionar versão do PHP** (Select PHP Version).
- No alto da tela existe um seletor com a versão do PHP e, abaixo, uma lista de extensões com caixinhas.
- **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.
- 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.
- 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

- Volte ao endereço da sua página de conferência, por exemplo `https://seusite.com.br/sistema/checagem-4821.php`.
- Atualize forçando a limpeza do cache: `Ctrl + F5` no Windows, `Cmd + Shift + R` no Mac. Ou abra em uma janela anônima.
- 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.

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

- Volte ao **Gerenciador de Arquivos**, entre na pasta, selecione o arquivo `checagem-4821.php`.
- Clique em **Excluir** (Delete).
- Esvazie a **Lixeira** (Trash) do Gerenciador de Arquivos, porque o arquivo excluído costuma ficar lá.
- Abra o endereço da página no navegador de novo. O esperado agora é erro 404, ou seja, endereço não encontrado.

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

- Pergunte ao fornecedor do sistema em quais versões de PHP ele é homologado.
- Pergunte ao suporte da hospedagem em quais dessas versões o loader está disponível.
- 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 |

## 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](https://docs.cpanel.net/ea4/php/php-options-php-loader-ioncube6/).

