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.

Resposta curta: 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 é.
Neste artigo
- A validação é por nome e começa na porta 80
- Teste com um arquivo seu antes de pedir o certificado
- O que cada mensagem de erro já prova
- Como corrigir cada uma das três causas
- Emitir manualmente pelo plugin e escolher os domínios do certificado
- Rotina mensal para achar a falha antes do certificado vencer
- Como explicar ao cliente sem prometer prazo
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.brvalidar não ajuda em nadaloja.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://parahttps://. 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, é 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.
# 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:
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:
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/302parahttps://no mesmo host e preservando o caminho, terminando em200com o texto cru: está tudo certo, pode emitir.301/302para a home, para outro host, ou que perde o/.well-known/acme-challenge/...noLocation:: 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.404com 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.
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:
<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 755em.well-knowne emacme-challenge,644no arquivo. Confira comls -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-knownjunto. Abra exceção explícita para.well-knownou remova a regra. - ModSecurity. Um 403 sem nada no
.htaccesscostuma 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.
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:
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-knownno 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. Um301no 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
.htaccesssozinhos 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-challengee observe onde a requisição termina:
# 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:
404comurl_effectiveno mesmo host e terminando no mesmo caminho/.well-known/acme-challenge/ping-...(mesmo que emhttps://): caminho livre. O arquivo real seria servido quando existisse.url_effectiveapontando 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:
Quando a causa é DNS, troque a segunda frase:
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.
Referências
- Documentação oficial (cpanel) — The Let's Encrypt Plugin. Consultado em 2026-09-16.