# As três causas do SSL não emitido em subdomínio no cPanel

Como ler a mensagem de erro de validação e decidir, antes de mexer em qualquer coisa, se o problema é DNS, redirecionamento ou bloqueio na pasta de verificação.

> o erro de validação do Let's Encrypt no cPanel cai em três causas: DNS do subdomínio apontado para outro servidor, redirecionamento que descarta o caminho de /.well-known/acme-challenge/ ou a pasta bloqueada por permissão, WAF ou regra contra arquivos ocultos. A mensagem de erro diz qual é.

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

---

## A validação é por nome e começa na porta 80

O certificado gratuito não é "liberado" por um botão. Ele é emitido depois que a autoridade certificadora comprova que quem pediu controla aquele nome. No cPanel, essa comprovação acontece pelo desafio HTTP: o servidor grava um arquivo com um token dentro de `/.well-known/acme-challenge/` na raiz do site e a autoridade tenta ler esse arquivo por `http://` naquele nome exato.

Duas consequências práticas saem daí, e elas explicam quase tudo que dá errado:

- A validação é **por nome**, não por conta. `exemplo.com.br` validar não ajuda em nada `loja.exemplo.com.br`. Cada nome no certificado precisa passar sozinho.
- A validação **começa em HTTP, na porta 80**, antes de qualquer HTTPS existir, mas o cliente ACME **segue redirecionamentos**, inclusive de `http://` para `https://`. Forçar HTTPS com 301 não quebra a validação por si só. Quebra quando o redirecionamento descarta o caminho do token (manda tudo para a home ou para uma landing), quando joga para outro host que não tem o arquivo, ou quando o vhost de destino tem outra raiz e o arquivo não existe lá.

Por isso a exceção do `.well-known` no `.htaccess` é boa prática, não antídoto universal: ela evita que você dependa do destino do redirecionamento estar certo. Em muitos sites que forçam HTTPS corretamente, a emissão funciona sem exceção nenhuma.

O plugin de Let's Encrypt do cPanel, descrito na [documentação oficial do cPanel](https://docs.cpanel.net/knowledge-base/third-party/the-lets-encrypt-plugin/), é instalado pelo administrador do servidor (root, via WHM, pelo script `/usr/local/cpanel/scripts/install_lets_encrypt_plugin`) e passa a aparecer na área de Segurança do cPanel do usuário. Ele automatiza a emissão e a renovação, mas não tem como contornar um redirecionamento que perde o caminho, uma permissão errada ou um DNS apontado para outro lugar. Quando falha, ele devolve o motivo em texto. Ler esse texto antes de mexer em qualquer coisa economiza a maior parte do tempo do diagnóstico.

## Teste com um arquivo seu antes de pedir o certificado

Não tente emitir às cegas. Reproduza o que a autoridade vai fazer, com um arquivo seu, que você controla e pode abrir no navegador.

Primeiro descubra a raiz correta do subdomínio. No cPanel, em Domínios, cada subdomínio tem um diretório próprio (`/home/usuario/loja`, `/home/usuario/public_html/loja`, o que for). Criar o arquivo no `public_html` do domínio principal quando o subdomínio aponta para outra pasta é o erro clássico que faz o teste "falhar" sem que haja problema nenhum.

```bash
# ajuste o caminho para a raiz REAL do subdomínio
mkdir -p ~/loja/.well-known/acme-challenge
echo "teste-dcv-ok" > ~/loja/.well-known/acme-challenge/teste.txt
```

Agora leia de fora, começando por HTTP, exatamente como o desafio é buscado. Primeiro sem seguir redirecionamento, para ver a cadeia crua:

```bash
curl -s -D - -o /dev/null http://loja.exemplo.com.br/.well-known/acme-challenge/teste.txt
```

Depois seguindo a cadeia até o fim, que é o que o cliente ACME faz:

```bash
curl -sL -D - http://loja.exemplo.com.br/.well-known/acme-challenge/teste.txt
```

O resultado que importa é o do segundo comando: `200` no final da cadeia e, no corpo, o texto cru `teste-dcv-ok`. Interprete assim:

- `301`/`302` para `https://` **no mesmo host e preservando o caminho**, terminando em `200` com o texto cru: está tudo certo, pode emitir.
- `301`/`302` para a home, para outro host, ou que perde o `/.well-known/acme-challenge/...` no `Location:`: aqui a validação quebra.
- Redirecionamento que preserva o caminho mas termina em `404`: o vhost de destino tem outra raiz, e o arquivo não está lá.
- `403`: permissão, regra de segurança ou proteção de conteúdo.
- `404` com HTML do WordPress logo de cara: a requisição chegou ao site errado ou o arquivo está em outra raiz.
- Nenhuma resposta, timeout ou conteúdo de outro site: DNS apontado para outro servidor.

Um detalhe que engana: testar direto em `https://`, ou no navegador já logado no painel, não reproduz o desafio. Comece sempre em `http://` e olhe a cadeia inteira.

## O que cada mensagem de erro já prova

Os trechos abaixo são **exemplos ilustrativos** do tipo de mensagem que o AutoSSL e o plugin costumam exibir. Não são amostra medida nem transcrição literal da sua instalação: use-os para reconhecer o padrão, não para comparar palavra por palavra.

| Trecho da mensagem (exemplo) | O que isso já prova | Causa provável | Primeira verificação |
|---|---|---|---||
| "resolved to an IP address that does not exist on this server" | A requisição nem chegou neste servidor | DNS do subdomínio em outro lugar | `dig +short loja.exemplo.com.br` |
| "the web server responded with the following error: 404" | Chegou ao servidor (direto ou após redirecionamento), mas o arquivo não foi encontrado | Raiz do vhost final diferente da que você usou, ou site capturando a rota | Conferir Document Root no cPanel |
| "...but the web server responded with a redirect" / `Location: https://...` | Chegou e foi desviado; falta saber se o destino ainda entrega o token | Redirecionamento para a home, para outro host, ou que descarta o caminho | `curl -sL -D -` no arquivo de teste |
| "the web server responded with the following error: 403" | Chegou e foi bloqueado de propósito | Permissão do diretório, ModSecurity, regra contra arquivos ocultos, bloqueio de IP | `ls -ld` na pasta e log de erro |
| "the content did not match" / "unexpected content" | Chegou, respondeu 200, mas entregou outra coisa | Página de erro customizada, cache ou proxy respondendo no lugar | Abrir o arquivo de teste e olhar o corpo |
| Timeout, conexão recusada, sem resposta | Porta 80 não respondeu para fora | Firewall, CDN em modo proxy, servidor antigo ainda respondendo | `curl -v` e verificação do IP |

A lógica é sempre a mesma: a mensagem diz **em que etapa** a leitura parou. DNS é antes de chegar. Redirecionamento perdido e 403 são depois de chegar. Conteúdo errado é depois de responder. Você só precisa decidir em qual das três está.

## Como corrigir cada uma das três causas

### DNS do subdomínio apontado para outro servidor

É a causa mais chata porque parece problema de hospedagem e não é. O subdomínio existe no cPanel, a pasta existe, mas a zona DNS que o mundo consulta está no registrador, na Cloudflare ou no provedor antigo.

```bash
dig +short loja.exemplo.com.br
dig +short exemplo.com.br
```

Compare com o IP do servidor (visível no cPanel, na barra lateral de informações gerais). Se o subdomínio devolve outro IP, ou devolve IPs da Cloudflare, a validação por HTTP só funciona se a requisição realmente chegar até aqui. Em CDN com proxy ativado, isso normalmente funciona, desde que a CDN não esteja servindo cache antigo nem reescrevendo o destino por conta própria. Em dúvida, desative o proxy (deixe o registro só em DNS) durante a emissão e reative depois.

Se a zona é externa, crie o registro A do subdomínio apontando para o IP do servidor e espere a propagação antes de tentar de novo. Emitir com DNS errado só produz mais uma linha de erro no histórico.

### Redirecionamento que descarta o caminho do desafio

O que quebra a validação não é redirecionar, é redirecionar **perdendo o destino**: mandar a raiz para uma landing page, jogar o subdomínio inteiro para o domínio principal, forçar `www` para um host cuja raiz é outra pasta, ou apontar para um vhost HTTPS que não tem o arquivo. Plugins de SSL do WordPress e trechos colados de tutoriais fazem isso com frequência, geralmente com `RewriteRule ^(.*)$ https://dominio.com.br/ [R=301,L]`, que descarta tudo o que vinha depois da barra.

A correção defensiva, que funciona independentemente do destino, é uma exceção no topo do `.htaccess` da raiz daquele subdomínio, antes de todo o resto:

```apache
<IfModule mod_rewrite.c>
RewriteEngine On
# entrega o desafio de validação no próprio host, sem depender do redirecionamento
RewriteRule ^\.well-known/acme-challenge/ - [L]
</IfModule>

# ...aqui embaixo continuam as regras de HTTPS, www e WordPress
```

Em Apache 2.4 você pode usar `[END]` no lugar de `[L]` para garantir que nenhum novo ciclo de reescrita reentre na regra. Se o redirecionamento não estiver no `.htaccess` e sim em Redirects do cPanel, remova a entrada lá e refaça o teste. Se estiver no WordPress (plugin de SSL, plugin de manutenção, redirecionamento de domínio), desative o plugin durante a emissão, valide, emita e reative.

Repita o `curl -sL` depois de cada alteração. Você quer ver o texto cru no fim da cadeia, não um `301` "quase certo" apontando para lugar nenhum.

### Pasta de validação bloqueada por permissão, WAF ou regra de arquivo oculto

Aqui o servidor recebe, entende e recusa. Quatro suspeitos, nessa ordem:

- **Permissão e dono.** O diretório precisa ser legível pelo servidor web. `chmod 755` em `.well-known` e em `acme-challenge`, `644` no arquivo. Confira com `ls -ld ~/loja/.well-known ~/loja/.well-known/acme-challenge`.
- **Regra que bloqueia arquivos ocultos.** Muita configuração de "segurança" inclui algo como `RedirectMatch 404 /\..*$` ou uma regra negando diretórios iniciados por ponto. Isso mata `.well-known` junto. Abra exceção explícita para `.well-known` ou remova a regra.
- **ModSecurity.** Um 403 sem nada no `.htaccess` costuma ser regra de WAF. O log de erro do domínio (Métricas, Erros, no cPanel) mostra a regra disparada. Peça ao administrador para desativar aquele ID de regra para o domínio, não o ModSecurity inteiro.
- **Hotlink e Leech Protection.** O Hotlink Protection do cPanel vem com a opção "Allow direct requests" marcada, ou seja, requisições sem referer passam normalmente e ele raramente é o culpado. Ele só vira causa de 403 se alguém desmarcou essa opção, ou se o Leech Protection está ativo cobrindo aquele diretório. Verifique o estado das duas opções antes de sair desligando coisas.

Um quinto caso, mais raro: bloqueio por país ou por faixa de IP no IP Blocker. A validação vem de vários endereços, inclusive de fora do Brasil. Bloqueio geográfico amplo impede a emissão.

## Emitir manualmente pelo plugin e escolher os domínios do certificado

Com o `curl -sL` devolvendo o texto cru, aí sim vale abrir o plugin. No cPanel, em Segurança, a interface do Let's Encrypt lista os domínios e subdomínios da conta com caixas de seleção e permite emitir um certificado cobrindo os nomes escolhidos, conforme descrito na [documentação do plugin](https://docs.cpanel.net/knowledge-base/third-party/the-lets-encrypt-plugin/).

A decisão que mais importa é **quais nomes entram**. Um certificado com vários nomes só é emitido se todos passarem na validação. Um único subdomínio quebrado derruba a emissão inteira, e o site principal fica sem certificado por causa de um `mail.` que aponta para outro provedor.

Regras práticas para montar a seleção:

| Nome | Incluir quando | Deixar de fora quando |
|---|---|---||
| `dominio.com.br` e `www` | Sempre, juntos | Nunca |
| Subdomínio do site (`loja`, `blog`, `app`) | Quando aponta para este servidor e passou no teste | Quando está em outro servidor ou ainda em construção |
| `mail.` e `webmail.` | Quando o e-mail é hospedado aqui e o cliente configura o Outlook ou celular usando `mail.dominio.com.br` | Quando o MX está no Google Workspace, Zoho, Titan ou outro provedor |
| `cpanel.`, `webdisk.`, `autodiscover.`, `autoconfig.` | Quando a zona DNS é gerenciada neste servidor e esses registros resolvem | Quando a zona é externa e esses registros não existem |
| Subdomínio atrás de CDN com proxy | Só depois de validar com o `curl` | Enquanto o proxy estiver interferindo |

Estratégia que evita retrabalho: se você tem muitos nomes, emita primeiro um certificado com o domínio principal e o `www`, confirme que ficou instalado, e só depois inclua os subdomínios de serviço. É mais rápido do que caçar qual dos dez nomes está derrubando o lote.

Sobre `mail.` e `webmail.`: incluir evita o aviso de certificado no cliente de e-mail quando o servidor de entrada e saída é `mail.dominio.com.br`. Se o cliente usa o hostname do servidor de hospedagem na configuração, o aviso não aparece de qualquer forma e você pode deixar fora. Se o e-mail está em outro provedor, incluir é dano garantido: o nome não resolve para cá, a validação falha e leva o resto junto.

Depois de emitir, confirme o que foi instalado de fato, sem confiar na tela verde:

```bash
echo | openssl s_client -connect loja.exemplo.com.br:443 -servername loja.exemplo.com.br 2>/dev/null \
  | openssl x509 -noout -subject -dates
```

O token do diagnóstico pontual pode ir embora quando terminar: `rm ~/loja/.well-known/acme-challenge/teste.txt`. A rotina de monitoramento da próxima seção não depende dele existir.

## Rotina mensal para achar a falha antes do certificado vencer

O valor aqui não está em resolver um site, está em resolver o mesmo problema em trinta sem repensar do zero. Transforme o processo acima em rotina.

- Antes de migrar DNS de qualquer cliente, coloque a exceção do `.well-known` no topo do `.htaccess`. É a mesma linha em todo site. Mantenha o trecho em um snippet no seu editor.
- Depois de apontar o DNS, rode o teste do arquivo de texto antes de pedir o certificado. Não peça emissão sem ver o **texto cru no fim da cadeia** do `curl -sL`. Um `301` no meio do caminho é aceitável desde que o caminho do token seja preservado e o destino entregue o arquivo.
- Ao ativar plugin de SSL, cache ou segurança no WordPress, refaça o teste. Muitos deles reescrevem o `.htaccess` sozinhos e podem reintroduzir um redirecionamento que descarta o caminho.
- Mantenha uma lista dos nomes que **não** devem entrar no certificado de cada cliente (tipicamente `mail.` de quem usa provedor externo). Isso evita que o próximo colega inclua tudo e quebre a renovação.
- Uma vez por mês, varra a carteira. Como não há arquivo de teste permanente nas raízes, peça um caminho inexistente dentro de `acme-challenge` e observe **onde a requisição termina**:

```bash
# dominios.txt com um nome por linha
while read d; do
  printf '%s -> ' "$d"
  curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' \
    "http://$d/.well-known/acme-challenge/ping-$(date +%s)"
done < dominios.txt
```

Como ler a saída:

- `404` com `url_effective` no mesmo host e terminando no mesmo caminho `/.well-known/acme-challenge/ping-...` (mesmo que em `https://`): caminho livre. O arquivo real seria servido quando existisse.
- `url_effective` apontando para a home, para outro domínio, ou sem o caminho do token: sinal de alerta, a renovação tende a falhar.
- `403`: bloqueio no diretório, trate pela seção anterior antes que o certificado vença.
- Timeout ou código estranho: DNS ou firewall, confira o IP.

Você descobre o problema agora, não no dia em que o navegador mostrar o aviso vermelho para o cliente. Para checar validade em lote, o mesmo padrão com `openssl` e `-dates` resolve, e o resultado cabe numa planilha de manutenção.

## Como explicar ao cliente sem prometer prazo

O cliente não precisa saber o que é ACME. Ele precisa entender que o problema não é "o servidor não quis dar o certificado" e que existe uma ação concreta em andamento.

Frase pronta, para copiar:

> **** O certificado só é emitido depois que a autoridade certificadora consegue ler um arquivo de verificação dentro do seu subdomínio. Hoje esse acesso está sendo desviado para outro endereço antes de o arquivo ser entregue, então a emissão é recusada. Já identifiquei onde o desvio acontece, vou corrigir e solicitar a emissão de novo.

Quando a causa é DNS, troque a segunda frase:

> **** Hoje o endereço desse subdomínio ainda aponta para o servidor antigo, então a verificação não chega até a hospedagem atual. Assim que o apontamento propagar, solicito a emissão.

Evite prometer hora. Propagação de DNS não está sob seu controle e a autoridade impõe limites de tentativas por domínio em janelas de tempo, o que significa que insistir em emitir repetidamente pode te deixar esperando mais do que se você tivesse corrigido a causa antes de clicar. Corrija, teste com o `curl`, emita uma vez.

E a recomendação que contraria o instinto comercial: na maioria das falhas de emissão em subdomínio, não há nada para comprar. Não é falta de recurso no plano nem limitação do servidor. É uma regra de redirecionamento que perde o caminho, um registro A apontado para o lugar errado ou uma permissão de diretório. Trocar de plano não corrige nenhuma das três.

