Use este checklist de resolução de problemas para diagnosticar registros DNS, atrasos de propagação e timing de SSL, com passos simples de verificação.
“Domínio personalizado não funciona” é um termo genérico para algumas falhas diferentes. Seu navegador mostra o sintoma, não a causa. Antes de mudar qualquer coisa, descreva exatamente o que você está vendo.
Sintomas típicos incluem:
Na maior parte das vezes, apenas uma coisa está errada:
Antes de solucionar, certifique-se de ter acesso a dois lugares: onde você edita registros DNS (registrador ou provedor DNS) e onde você anexa o domínio no lado da hospedagem. Por exemplo, se você está conectando um app implantado no Koder.ai a um domínio personalizado, você precisa de acesso ao DNS do domínio e às configurações de domínio no painel de deploy/hospedagem do app.
Algumas correções são instantâneas (como corrigir um erro de digitação). Outras levam tempo. Mudanças de DNS podem demorar a aparecer, e o SSL geralmente só conclui depois que o DNS aponta corretamente e o domínio é alcançável. O objetivo é parar de adivinhar e confirmar cada camada em ordem.
A maioria dos problemas de domínio se resume a uma incompatibilidade entre (1) o hostname que você está testando, (2) onde o DNS é gerenciado e (3) para onde o registro realmente aponta. Quando esses três alinharem, o SSL geralmente é o último passo.
Os domínios têm duas formas comuns: o domínio root (example.com, também chamado apex) e subdomínios (www.example.com, app.example.com). Eles são relacionados, mas podem ter registros DNS diferentes. Então é normal o www funcionar enquanto o apex falha, ou o contrário.
Nameservers decidem quem está no comando da sua zona DNS. Se você comprou um domínio em uma empresa mas os nameservers apontam para outra, você deve editar o DNS onde os nameservers apontam. Muitos casos de “eu atualizei, mas nada mudou” acontecem porque os registros foram editados no painel errado.
Aqui está o que os principais tipos fazem:
www)TTL é o temporizador de “por quanto tempo armazenar em cache isto”. TTL menor significa caches atualizando mais rápido. TTL maior significa que você pode ter que esperar mais, mesmo depois de corrigir o registro. Ver o valor antigo por um tempo pode ser normal.
Quando um domínio personalizado falha, você normalmente consegue classificar em um de quatro grupos: DNS não resolve, DNS resolve para o lugar errado, SSL não está pronto, ou falha só para algumas pessoas por causa do cache.
Use esta árvore de decisão:
www funciona mas o domínio root não (ou vice-versa), provavelmente você configurou apenas um hostname, ou tem regras de redirecionamento conflitantes.Vá mais rápido anotando o hostname exato que falha (apex vs www) e a mensagem de erro exata. Em plataformas que automatizam domínios e certificados, a diferença entre “não encontra host” e “certificado pendente” diz se você deve consertar registros DNS ou simplesmente aguardar o SSL depois que o DNS ficar visível.
Muitos erros de domínio começam com uma simples incompatibilidade: você configurou o DNS para um hostname, mas está testando outro.
Primeiro, anote o hostname exato que você quer publicar. O domínio root parece com example.com. Um subdomínio parece com www.example.com ou app.example.com. Esses são registros DNS separados, então “o www funciona” não significa que o domínio root também funcionará.
Em seguida, encontre o alvo esperado na sua plataforma de hospedagem. Algumas plataformas dão um endereço IP (para um registro A ou AAAA). Outras dão um hostname de destino (para um CNAME). Se o seu host fornece um valor na tela de configuração de domínio, trate isso como a fonte de verdade.
Antes de mudar qualquer coisa, registre o que está configurado atualmente. Mantenha simples:
Também confirme que você está editando a zona DNS correta. É fácil atualizar o domínio errado, o ambiente errado ou a conta errada do provedor.
Muitos problemas são só o tipo de registro errado para o hostname que você está tentando conectar. Comece separando dois casos: o domínio root (example.com) e um subdomínio (www.example.com). Eles se comportam de maneira diferente em muitos provedores DNS.
Um registro A aponta um nome para um endereço IPv4. Muitas configurações usam um A para o domínio root porque alguns provedores não permitem CNAME no apex. Se seu host te deu um IP, um A é geralmente correto.
Um registro AAAA é a versão IPv6. Um AAAA sobrando apontando para um destino antigo pode criar comportamento confuso de “funciona para mim”, porque alguns visitantes atingirão IPv6 enquanto outros atingirã o IPv4. Se seu host não deu um alvo IPv6, remover um AAAA incorreto frequentemente corrige falhas inconsistentes.
Um CNAME aponta um subdomínio para outro hostname (muito usado para www). É útil quando o host quer que você aponte para um endpoint nomeado que pode mudar por trás dos panos.
Um TXT é para verificação e challenges (incluindo alguns checks de SSL). Erros comuns incluem colocar o TXT no nome errado (root vs _acme-challenge vs um subdomínio), adicionar espaços extras ou colar o valor errado.
Antes de seguir, procure conflitos. Estes são os que causam mais problemas:
www ou para o domínio rootMuitos casos de “domínio personalizado não funciona” não têm a ver com o valor do registro. Acontecem porque o registro foi adicionado no provedor errado. Se seu domínio usa os nameservers do Provedor A, mudar registros no painel do Provedor B não fará nada, mesmo se os registros parecerem corretos lá.
Verifique quais nameservers seu domínio está realmente usando. Normalmente você vê isso nas configurações de domínio do seu registrador em “Nameservers”. Para uma segunda opinião, pergunte ao DNS diretamente do seu computador:
dig NS example.com
Os nameservers retornados por esse comando são os autoritativos.
Uma checagem rápida de sanidade:
ns1... e ns2..., esses valores exatos devem aparecer no registrador.Se você atualiza registros no provedor errado, frequentemente verá dois painéis que não batem. Só os nameservers autoritativos importam.
Também fique de olho em atrasos após mudar nameservers no registrador. Durante a janela de transição, os resultados podem parecer inconsistentes dependendo de onde você testa. Se os nameservers ainda estiverem mudando, pause edições de registro até que o conjunto de nameservers esteja estável e então continue.
“Propagação” não é um único interruptor. É uma cadeia de caches DNS (ISP, operadora de telefone, resolvedores públicos e seus próprios dispositivos) atualizando em velocidades diferentes. Por isso seu domínio pode funcionar para um colega e falhar para você.
TTL (time to live) indica por quanto tempo caches podem guardar uma resposta. Se o TTL antigo era 1 hora, algumas pessoas continuarão vendo o valor antigo por perto de uma hora. Diminuir o TTL ajuda só se você o fez antes de realizar a mudança.
Para separar atrasos de cache de erros reais, faça algumas checagens rápidas:
Se o registro estiver errado em qualquer lugar que você verificar (IP errado, falta de www, CNAME antigo), corrija. Se os registros parecerem corretos na maioria dos lugares mas uma rede ainda mostrar o valor antigo, geralmente é atraso de cache.
Certificados SSL costumam falhar por uma razão básica: o provedor de certificados não consegue validar o domínio até o DNS apontar para o lugar correto de forma consistente.
A sequência normal é simples:
Bloqueios comuns são fáceis de perder. Um A ou CNAME errado manda as checagens de validação para o servidor errado. Um AAAA desatualizado pode sobrepor seu A funcional para alguns visitantes, fazendo o HTTPS falhar só para eles. Faltar um TXT exigido pode impedir a emissão do certificado.
Use sintomas para separar “ainda emitindo” de “mal configurado”:
Enquanto espera, não fique mudando registros. Cada mudança reinicia o relógio e pode criar um mundo dividido onde diferentes redes veem respostas diferentes. Configure os registros corretos uma vez, então re-cheque resolução e verificação até o certificado ser emitido.
Se você usa uma plataforma como Koder.ai, o fluxo mais seguro é o mesmo: confirme que o DNS aponta para o alvo esperado, remova registros AAAA incorretos se existirem, e deixe o SSL um tempo depois que o DNS estiver estável.
Boa solução de problemas é principalmente comparação: o que você vê versus o que você espera. Não dependa de “carrega no meu celular”. Use checagens repetíveis.
Use uma ferramenta de consulta DNS (como nslookup ou dig) e confirme que o valor retornado bate com o que você pretendia (um IP para A ou AAAA, um hostname para CNAME, um token para TXT).
# Apex (root) domain
dig example.com A
dig example.com AAAA
# www subdomain
dig www.example.com CNAME
# TXT (frequentemente usado para verificação)
dig example.com TXT
Cheque ambos os nomes que você pode estar usando: o apex (example.com) e www (www.example.com). É comum um estar correto enquanto o outro ainda aponta para um lugar antigo.
Abra tanto http:// quanto https:// para o apex e para www. Você quer um domínio “principal” claro e um redirecionamento limpo.
www) e redirecione o outro para ele.Se os resultados diferirem por rede, provavelmente você está vendo cache ou propagação. Mantenha um pequeno registro: o que você mudou, onde você mudou, o horário e o que observou.
A maioria dos problemas de DNS e SSL não são mistérios. São pequenos erros que fazem você checar a coisa errada, ou ficar mudando tudo rápido demais para ter uma leitura clara.
O gasto de tempo mais comum é editar DNS em dois lugares. Isso frequentemente acontece após trocar nameservers: você atualiza registros no registrador, mas o DNS está realmente hospedado em outro lugar (ou o contrário). Tudo parece correto em um painel, mas nada muda publicamente.
Outro erro clássico é tentar colocar um CNAME no domínio root com um provedor que não suporta isso. Talvez você precise de um registro A, ou de um registro do tipo ALIAS/ANAME se seu provedor de DNS oferecer.
IPv6 também pode causar dores de cabeça. Deixar um AAAA antigo pode mandar alguns visitantes para o servidor errado enquanto outros acessam o IPv4 correto.
Tenha cuidado com registros “só por precaução”. Múltiplos registros A podem se comportar como balanceamento acidental se um dos alvos estiver errado, especialmente quando aponta um domínio personalizado para um app hospedado.
Uma regra final: pare de reiniciar o relógio.
Pequenas mudanças calmas vencem ajustes constantes.
Você lança um app novo e configura tanto example.com quanto www.example.com. Alguns minutos depois, www.example.com carrega bem, mas o domínio root mostra erro DNS, carrega um site antigo ou o HTTPS fica pendente. Esse padrão é comum e normalmente tem uma causa pequena.
Comece com a pergunta chata: você está editando o DNS no lugar certo? Se seu domínio está registrado em uma empresa mas o DNS está hospedado em outra, você pode passar o dia mudando registros que nunca entrarão em vigor. Verifique os nameservers primeiro e depois abra o painel de DNS do provedor para o qual esses nameservers apontam.
Depois, compare os dois hostnames. www é tipicamente um CNAME. O domínio root é mais complicado: muitos provedores não permitem CNAME no apex, então ele frequentemente precisa de um registro A para um IP, ou de um registro ALIAS/ANAME se suportado.
Um caminho de decisão que funciona na prática:
example.com não tem registro (ou aponta para outro lugar)? Ajuste o registro do apex.O estado final correto é chato: tanto example.com quanto www.example.com levam ao mesmo app, um é canônico (o outro redireciona), e o HTTPS é válido.
Quando uma configuração de domínio falha, a maioria das correções vem de alguns checagens rápidas. Rode estas antes de mudar qualquer outra coisa.
Depois que o DNS estiver claramente correto, então verifique o SSL. Muitas plataformas só emitem o certificado depois que conseguem resolver seu domínio para o alvo certo de forma consistente. Se você checar cedo demais, pode confundir um atraso normal com um erro real.
Se você estiver adicionando um domínio personalizado a um app implantado no Koder.ai, trate a tela de configuração do domínio como referência para o alvo esperado, então re-cheque o status apenas depois que o DNS teve tempo de propagar.
A forma mais rápida de evitar repetir erros de DNS e SSL é manter uma nota curta de “configuração de domínio” para cada projeto. É um runbook reutilizável que você pode copiar na próxima vez que lançar.
Mantenha nos docs do projeto e preencha antes de tocar no DNS:
Durante o lançamento, faça uma pessoa ser a dona do DNS. DNS quebra mais quando duas pessoas “consertam” coisas diferentes ao mesmo tempo (por exemplo, uma troca nameservers enquanto outra edita registros).
No lado da hospedagem, planeje reversões seguras. Se sua plataforma suporta snapshots ou rollback, tire um snapshot antes de mudar roteamento para poder voltar ao último estado conhecido que funcionava rapidamente. Se você constrói no Koder.ai, pode usar o Planning Mode para anotar os passos do domínio, aplicá‑los em ordem e reverter se uma mudança quebrar a produção.
Se você confirmou o DNS e ainda vê falhas, pare de adivinhar e escale com evidências:
Ao escalar, inclua o hostname, registros esperados, resultados de resolvers atuais e timestamps. Isso transforma um processo lento em um conserto rápido.
Geralmente significa que uma camada da cadeia está errada: DNS não está resolvendo, DNS resolve para o destino errado, o servidor/host não reconhece seu hostname, ou HTTPS/SSL ainda não foi emitido. Comece anotando o erro exato que aparece e o hostname que você digitou (apex vs www).
Porque example.com (o apex) e www.example.com são hostnames separados com registros DNS distintos. É comum ter um CNAME correto para www enquanto o apex não tem registro A, tem um A errado, ou o provedor de DNS não suporta a configuração desejada.
Verifique os nameservers do domínio no seu registrador e compare com o provedor de DNS que você está editando. Só o provedor listado nos nameservers ativos é autoritativo; editar registros em outro lugar não mudará o que a internet publica vê.
Use um registro A quando seu host fornecer um endereço IPv4, um registro AAAA apenas se o host fornecer um endereço IPv6, e um CNAME quando o host fornecer outro hostname (o mais comum para www). Registros TXT são para verificação e desafios e devem ser criados exatamente no nome que seu host especificar.
Um registro AAAA desatualizado ou incorreto pode enviar alguns visitantes por IPv6 para um servidor antigo enquanto outros vão para o IPv4 correto, criando a confusão de “funciona para mim”. Se seu host não forneceu um alvo IPv6, remover um AAAA incorreto costuma resolver.
Normalmente você configurou apenas um hostname no lado do hosting (apenas apex ou apenas www), ou há regras de redirecionamento conflitantes que fazem o navegador pular entre HTTP e HTTPS ou entre apex e www. Escolha um hostname canônico, configure ambos os hostnames e garanta um único caminho de redirecionamento limpo.
Sim — e esperar é a ação certa depois de confirmar que o DNS aponta para o destino correto em múltiplos locais. A emissão do certificado normalmente só termina quando o domínio resolve consistentemente para o destino esperado; ficar alternando registros pode reiniciar o processo.
TTL é o tempo que os resolvers guardam uma resposta em cache, então mesmo após corrigir um registro, algumas redes podem continuar servindo o valor antigo até o TTL expirar. Teste de duas redes diferentes (por exemplo, Wi‑Fi e dados móveis) e evite fazer mudanças repetidas no DNS para observar a propagação corretamente.
Use uma checagem repetível como dig ou nslookup para confirmar que as respostas A/AAAA/CNAME/TXT batem com o alvo esperado, e então teste http:// e https:// tanto no apex quanto em www. Se uma rede mostra respostas DNS diferentes de outra, trate como cache; se todas mostram valores errados, trate como erro de configuração.
No Koder.ai, trate a tela de configuração de domínio do app como a fonte de verdade para o alvo DNS esperado, então faça o DNS casar exatamente com isso no provedor autoritativo. Depois de mudar o DNS, dê tempo para assentar antes de checar o SSL, e use snapshots/rollback se você for ajustar o roteamento em um projeto em produção para voltar rapidamente a um estado que funcionava.
Se você confirmou que o DNS está correto e ainda vê falhas, reúna evidências e escale: inclua o hostname, os registros esperados, os resultados dos resolvers atuais e timestamps. Isso transforma um vai-e-vem lento em um conserto rápido.