Checklist de solução de problemas para domínios personalizados — DNS e SSL

O que “domínio personalizado não funciona” geralmente significa

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

• Uma página de “domínio não encontrado”
• O domínio carregando o site errado
• Um aviso de “inseguro” mesmo com HTTPS ativado
• Loops de redirecionamento (pulando entre http e https, ou entre o domínio root e o www)

Na maior parte das vezes, apenas uma coisa está errada:

• O DNS aponta para o lugar errado, ou o registro necessário está faltando
• O alvo de hospedagem não está configurado para esse hostname (o servidor não reconhece seu domínio)
• SSL não foi emitido ainda, foi emitido para um hostname diferente, ou não pode ser emitido porque o DNS não corresponde
• Cache esconde suas mudanças (cache do navegador, cache do resolvedor DNS ou valores antigos de TTL)

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.

Conceitos pequenos de DNS que importam (sem jargão)

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.

Tipos de registro DNS em linguagem simples

Aqui está o que os principais tipos fazem:

• A: aponta um nome para um endereço IPv4 (como 203.0.113.10)
• AAAA: aponta um nome para um endereço IPv6
• CNAME: aponta um nome para outro hostname (comum para www)
• TXT: armazena texto usado para verificação e segurança (checagens de propriedade, SPF e similares)

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.

Passo a passo: uma árvore de decisão simples para isolar a causa

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:

1. O domínio resolve de todo? Se você vê NXDOMAIN (ou “domínio não encontrado”), o registro está faltando, você está editando a zona DNS errada, ou os nameservers não são os que você pensa.
2. Se resolve, aponta para o alvo certo? Se a página carrega mas é o site errado, uma página parking ou um servidor antigo, o alvo A/AAAA/CNAME está errado ou um registro antigo está tomando prioridade.
3. Se aponta corretamente, a falha é só no HTTPS? Se HTTP funciona mas HTTPS mostra aviso de certificado, o SSL pode ainda estar sendo emitido, o hostname no certificado pode não bater, ou a plataforma pode estar esperando o DNS se estabilizar.
4. Funciona em um dispositivo ou rede mas não em outro? Trate como cache ou propagação.
5. Os redirecionamentos quebram (www vs apex)? Se 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.

Passo 1: confirme o hostname e o alvo esperado

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:

• Copie os registros DNS atuais para o hostname que você está alterando
• Anote quaisquer registros A, AAAA, CNAME e TXT existentes
• Registre o TTL

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.

Passo 2: escolha o tipo de registro DNS certo (A, AAAA, CNAME, TXT)

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:

• Um CNAME em um nome que também tem outros tipos de registro
• Múltiplos registros A ou AAAA para o mesmo nome quando você pretendia apenas um
• Registros antigos deixados para o www ou para o domínio root
• Registros TXT criados no hostname errado

Passo 3: verifique os nameservers para garantir que você está editando o lugar certo

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

Confirme os nameservers autoritativos

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:

• Se seu host de DNS te dá nameservers como ns1... e ns2..., esses valores exatos devem aparecer no registrador.
• Se você trocou de provedor de DNS recentemente, confirme que a troca está completa antes de editar mais registros.
• Se uma plataforma mostra “registros DNS sugeridos”, isso normalmente é orientação. Você ainda precisa adicionar os registros no provedor DNS autoritativo.

Por que acontece “eu atualizei, mas nada mudou”

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.

Passo 4: verificações de propagação e cache que realmente ajudam

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

• Teste em Wi‑Fi de casa ou escritório e depois em dados móveis
• Peça para alguém em outra rede tentar
• Use uma janela privada (para descartar redirects em cache)
• Reinicie seu dispositivo ou limpe o cache DNS local se souber como
• Verifique novamente o hostname exato (root vs www)

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.

Passo 5: tempo de emissão de SSL e por que “espere um pouco” é às vezes correto

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:

1. Configure os registros DNS corretos.
2. Espere até que eles resolvam corretamente de múltiplos locais.
3. Complete qualquer verificação requerida (frequentemente um registro TXT).
4. Aguarde a emissão do certificado.

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

• Ainda emitindo: HTTP pode funcionar, mas HTTPS mostra um certificado padrão temporário ou uma mensagem de “não válido ainda”.
• Mal configurado: você vê um site diferente, uma página de parking do ISP, ou a busca DNS falha (NXDOMAIN).

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.

Como verificar cada passo (sem chutar)

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.

Verifique respostas DNS contra o alvo esperado

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.

Verifique o comportamento do navegador (HTTP, HTTPS e redirects)

Abra tanto http:// quanto https:// para o apex e para www. Você quer um domínio “principal” claro e um redirecionamento limpo.

• Escolha um domínio canônico (ou apex ou www) e redirecione o outro para ele.
• Evite redirecionamentos de ping‑pong (A redireciona para B e B redireciona de volta para A).
• Se HTTP funciona mas HTTPS falha, o SSL está ou ainda sendo emitido ou o DNS está apontando para um lugar inesperado.

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.

Erros comuns que fazem perder horas

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.

• Não mude registros a cada poucos minutos.
• Não misture alvos antigos e novos ao mesmo tempo.
• Espere os caches assentarem antes de julgar resultados.

Pequenas mudanças calmas vencem ajustes constantes.

Um exemplo realista: www funciona mas o domínio root não

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:

• Nameservers errados ou inesperados? Conserte isso primeiro.
• Nameservers corretos mas example.com não tem registro (ou aponta para outro lugar)? Ajuste o registro do apex.
• Registros parecem corretos mas comportamento difere por dispositivo ou rede? Aguarde propagação e limpe caches.
• DNS resolve corretamente mas HTTPS está falhando ou travado? O SSL está esperando por um DNS consistente.

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.

Checklist rápido que você pode rodar em 5 minutos

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.

• Confirme que você está editando o DNS no lugar certo (compare seu painel com os nameservers autoritativos do domínio).
• Verifique o hostname e o alvo exato (sem subdomínio faltando, sem pontos a mais). Compare o tipo de registro (A, AAAA, CNAME, TXT) com o que seu host espera.
• Remova conflitos (CNAME junto com outros registros no mesmo nome, ou A/AAAA antigos que você não precisa mais).
• Cheque de duas perspectivas (dados móveis e Wi‑Fi). Se uma funciona e a outra não, geralmente é cache ou propagação.
• Respeite o TTL. Se o TTL for 300 segundos, espere 5 a 10 minutos antes de julgar. Se for 3600, espere perto de uma hora.

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.

Próximos passos: torne a configuração de domínio repetível para cada lançamento

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.

Um template simples de nota de configuração de domínio

Mantenha nos docs do projeto e preencha antes de tocar no DNS:

• Domínios e hostnames (root, www e quaisquer subdomínios)
• Tipos de registros esperados e alvos (A, CNAME, TXT) e de onde eles vêm
• Onde o DNS é editado (qual provedor) e os nameservers ativos
• Expectativas de SSL (quem emite, como é o estado “pronto”)
• Passos de verificação que você irá rodar (ferramenta e resultado esperado)

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.

Quando escalar (e para quem)

Se você confirmou o DNS e ainda vê falhas, pare de adivinhar e escale com evidências:

• O registrador mostra nameservers bloqueados ou você não consegue mudá‑los
• Edições de DNS não aparecem em lugar nenhum após a janela esperada de TTL
• SSL continua falhando horas depois do DNS resolver corretamente
• Você vê registros conflitantes que não consegue remover (bug na UI do provedor ou split DNS)

Ao escalar, inclua o hostname, registros esperados, resultados de resolvers atuais e timestamps. Isso transforma um processo lento em um conserto rápido.