Checklist per la risoluzione dei problemi di dominio personalizzato: DNS e SSL

Cosa significa di solito “custom domain not working”

“Custom domain not working” è una frase ombrello per alcuni tipi diversi di guasti. Il browser mostra il sintomo, non la causa. Prima di cambiare qualcosa, definisci cosa stai effettivamente vedendo.

Sintomi tipici includono:

• Una pagina “dominio non trovato”
• Il dominio carica il sito sbagliato
• Un avviso di “non sicuro” anche se HTTPS è abilitato
• Loop di redirect (rimbalzo tra http e https, o tra il dominio apex e www)

La maggior parte delle volte, c'è un solo problema alla base:

• Il DNS punta nel posto sbagliato, o il record necessario manca
• Il target di hosting non è configurato per quell'hostname (il server non riconosce il tuo dominio)
• SSL non è stato ancora emesso, è stato emesso per un hostname diverso, o non può essere emesso perché il DNS non corrisponde
• La cache nasconde le tue modifiche (cache del browser, cache del resolver DNS o valori TTL vecchi)

Prima di iniziare a risolvere, assicurati di avere accesso a due posti: dove modifichi i record DNS (registrar o provider DNS) e dove colleghi il dominio sul lato hosting. Per esempio, se stai collegando un'app distribuita su Koder.ai a un dominio personalizzato, ti servono l'accesso al DNS del dominio e le impostazioni del dominio nell'area hosting o di deployment dell'app.

Alcune correzioni sono istantanee (come correggere un errore di battitura). Altre richiedono tempo. Le modifiche DNS possono impiegare a comparire e SSL di solito non si completerà finché il DNS non punta correttamente e il dominio non è raggiungibile. L'obiettivo è smettere di indovinare e confermare ogni livello in ordine.

I piccoli concetti DNS che contano (senza gergo)

La maggior parte dei problemi di dominio si riduce a una discrepanza tra (1) l'hostname che stai testando, (2) dove è gestito il DNS, e (3) dove il record punta effettivamente. Quando questi tre elementi coincidono, SSL è di solito l'ultimo passo.

I domini hanno due forme comuni: il dominio root (example.com, chiamato anche apex) e i sottodomini (www.example.com, app.example.com). Sono correlati, ma possono avere record DNS diversi. Quindi è normale che www funzioni mentre l'apex fallisce, o viceversa.

I nameserver decidono chi è responsabile della tua zona DNS. Se hai comprato un dominio da una società ma i nameserver puntano a un'altra, devi modificare il DNS dove i nameserver puntano. Molti casi di “l'ho aggiornato ma non è cambiato nulla” succedono perché i record sono stati modificati nella dashboard sbagliata.

Tipi di record DNS in parole semplici

Ecco cosa fanno i principali tipi di record:

• A: punta un nome a un indirizzo IPv4 (per esempio 203.0.113.10)
• AAAA: punta un nome a un indirizzo IPv6
• CNAME: punta un nome a un altro hostname (comune per www)
• TXT: memorizza testo usato per verifiche e sicurezza (controlli di proprietà, SPF e simili)

Il TTL è il timer del “quanto a lungo mettere in cache questa risposta”. Un TTL basso significa che le cache si aggiornano più velocemente. Un TTL alto significa che potresti dover aspettare più a lungo, anche dopo aver corretto il record. Vedere il valore vecchio per un po' può essere normale.

Passo-passo: un semplice albero decisionale per isolare la causa

Quando un dominio personalizzato fallisce, di solito rientra in una di quattro categorie: il DNS non risolve, il DNS risolve nel posto sbagliato, SSL non è pronto, o fallisce solo per alcune persone a causa della cache.

Usa questo albero decisionale:

1. Il dominio risolve almeno? Se vedi NXDOMAIN (o “domain not found”), il record manca, stai modificando la zona DNS sbagliata o i nameserver non sono quelli che pensi.
2. Se risolve, punta al target giusto? Se la pagina si apre ma è il sito sbagliato, una pagina parked o un server vecchio, il target A/AAAA/CNAME è sbagliato o c'è un record rimasto che ha priorità.
3. Se punta correttamente, il problema è solo HTTPS? Se HTTP funziona ma HTTPS mostra un avviso sul certificato, SSL potrebbe essere ancora in fase di emissione, l'hostname sul certificato potrebbe non corrispondere, o la piattaforma sta aspettando che il DNS si stabilizzi.
4. Funziona su un dispositivo o rete ma non su un altro? Consideralo come caching o propagazione.
5. I redirect si rompono (www vs apex)? Se www funziona ma il dominio root no (o viceversa), probabilmente hai configurato solo un hostname, o hai regole di redirect in conflitto.

Procedi più velocemente annotando l'hostname esatto che fallisce (apex vs www) e l'errore esatto. Su piattaforme che automatizzano domini e certificati, la differenza tra “cannot find host” e “certificate pending” ti dice se devi correggere i record DNS o semplicemente aspettare SSL dopo che il DNS è visibile.

Passo 1: conferma l'hostname e il target previsto

Molti fallimenti di dominio iniziano con una semplice discrepanza: hai impostato il DNS per un hostname, ma stai testando un altro.

Per prima cosa, annota l'hostname esatto che vuoi mettere online. Il dominio root appare come example.com. Un sottodominio appare come www.example.com o app.example.com. Questi sono voci DNS separate, quindi “www funziona” non significa che il dominio root funzionerà.

Poi, trova il target previsto dalla tua piattaforma di hosting. Alcune piattaforme danno un indirizzo IP (per un record A o AAAA). Altre danno un hostname di destinazione (per un CNAME). Se il tuo host fornisce un valore nella schermata di configurazione del dominio, trattalo come fonte di verità.

Prima di cambiare qualsiasi cosa, cattura ciò che è attualmente impostato. Tienilo semplice:

• Copia i record DNS correnti per l'hostname che stai cambiando
• Nota eventuali record A, AAAA, CNAME e TXT esistenti
• Registra il TTL

Conferma anche che stai modificando la zona DNS corretta. È facile aggiornare il dominio sbagliato, l'ambiente sbagliato o l'account provider sbagliato.

Passo 2: scegli il tipo di record DNS giusto (A, AAAA, CNAME, TXT)

Molti problemi derivano dal tipo di record sbagliato per l'hostname che stai cercando di collegare. Inizia separando due casi: il dominio root (example.com) e un sottodominio (www.example.com). Si comportano diversamente in molti provider DNS.

Un record A punta un nome a un indirizzo IPv4. Molte configurazioni usano un record A per il dominio root perché alcuni provider non permettono un CNAME all'apex. Se il tuo host ti dà un IP, un A è di solito corretto.

Un record AAAA è la versione IPv6. Un AAAA rimasto che punta a una destinazione vecchia può creare comportamenti confusi “funziona per me”, perché alcuni visitatori useranno IPv6 mentre altri useranno IPv4. Se il tuo host non ti ha dato un target IPv6, rimuovere un AAAA errato spesso risolve fallimenti incoerenti.

Un CNAME punta un sottodominio a un altro hostname (spesso usato per www). È utile quando l'host vuole che tu punti a un endpoint nominato che può cambiare dietro le quinte.

Un TXT è per verifiche e challenge (inclusi alcuni controlli SSL). Errori comuni includono posizionare il TXT sul nome sbagliato (root vs _acme-challenge vs un sottodominio), aggiungere spazi extra o incollare il valore sbagliato.

Prima di continuare, cerca conflitti. Questi sono quelli che causano più problemi:

• Un CNAME su un nome che ha anche altri tipi di record
• Più record A o AAAA per lo stesso nome quando volevi solo uno
• Record vecchi lasciati per www o il dominio root
• Record TXT creati sul nome sbagliato

Passo 3: verifica i nameserver per assicurarti di modificare il posto giusto

Molti casi di “custom domain not working” non riguardano il valore del record. Succedono perché il record è stato aggiunto dal provider sbagliato. Se il tuo dominio usa i nameserver del Provider A, cambiare record nella dashboard del Provider B non farà nulla, anche se i record lì sembrano corretti.

Conferma i nameserver autorevoli

Controlla quali nameserver sta veramente usando il tuo dominio. Di solito puoi vederlo nelle impostazioni del dominio del registrar sotto “Nameservers”. Per un secondo parere, chiedi il DNS direttamente dal tuo computer:

dig NS example.com

I nameserver restituiti da quel comando sono quelli autorevoli.

Un controllo di base:

• Se il tuo host DNS ti dà nameserver tipo ns1... e ns2..., quegli stessi valori devono comparire al registrar.
• Se hai cambiato recentemente provider DNS, conferma che il passaggio sia completo prima di fare altre modifiche ai record.
• Se una piattaforma mostra “record DNS suggeriti”, è di solito una guida. Devi comunque aggiungere i record presso il provider DNS autorevole.

Perché succede “l'ho aggiornato ma nulla è cambiato”

Se aggiorni i record sul provider sbagliato, vedrai spesso due dashboard che non corrispondono. Soltanto i nameserver autorevoli contano.

Fai anche attenzione ai ritardi dopo aver cambiato i nameserver al registrar. Durante la finestra di transizione, i risultati possono apparire incoerenti a seconda da dove testi. Se i nameserver sono ancora in fase di cambio, metti in pausa le modifiche dei record finché l'insieme dei nameserver non è stabile, poi continua.

Passo 4: controlli di propagazione e cache che davvero aiutano

La “propagazione” non è un interruttore unico. È una catena di cache DNS (ISP, operatori mobili, resolver pubblici e i tuoi dispositivi) che si aggiornano a velocità diverse. Per questo motivo il tuo dominio può funzionare per un collega ma non per te.

Il TTL (time to live) dice alle cache per quanto tempo possono tenere una risposta. Se il TTL precedente era 1 ora, alcune persone continueranno a vedere il valore vecchio per quasi un'ora. Abbassare il TTL aiuta solo se lo hai fatto prima di effettuare la modifica.

Per separare i ritardi di cache dagli errori reali, fai alcuni controlli rapidi:

• Prova su Wi‑Fi di casa o ufficio, poi su dati mobili
• Chiedi a qualcuno su una rete diversa di provare
• Usa una finestra privata (per escludere redirect in cache)
• Riavvia il dispositivo o svuota la cache DNS locale se sai come farlo
• Ricontrolla l'hostname esatto (root vs www)

Se il record è sbagliato ovunque controlli (IP sbagliato, www mancante, CNAME vecchio), correggilo. Se i record sembrano corretti nella maggior parte dei posti ma una rete vede ancora il valore vecchio, è di solito un ritardo di cache.

Passo 5: tempistiche SSL e perché a volte “aspetta un po'” è corretto

I certificati SSL falliscono di solito per una ragione semplice: il provider del certificato non può convalidare il dominio finché il DNS non punta al posto giusto in modo coerente.

La sequenza normale è semplice:

1. Imposta i record DNS corretti.
2. Aspetta che risolvano correttamente da più posti.
3. Completa eventuali verifiche richieste (spesso un record TXT).
4. Lascia che l'emissione del certificato si completi.

I blocchi comuni sono facili da perdere di vista. Un A o CNAME sbagliato manda i controlli di validazione al server sbagliato. Un AAAA obsoleto può sovrascrivere il tuo A funzionante per alcuni visitatori, quindi HTTPS fallisce solo per loro. La mancanza di un TXT richiesto può impedire alla piattaforma di emettere un certificato.

Usa i sintomi per separare “ancora in emissione” da “malconfigurato”:

• Ancora in emissione: HTTP potrebbe funzionare, ma HTTPS mostra un certificato predefinito temporaneo o un messaggio del tipo “not valid yet”.
• Malconfigurato: vedi un sito diverso, una pagina di parking dell'ISP, o la ricerca DNS fallisce (NXDOMAIN).

Mentre aspetti, evita di continuare a cambiare i record. Ogni modifica resetta l'orologio e può creare un mondo diviso dove reti diverse vedono risposte diverse. Imposta i record corretti una volta, poi ricontrolla risoluzione e verifiche finché il certificato non è emesso.

Se usi una piattaforma come Koder.ai, il flusso più sicuro è lo stesso: conferma che il DNS punti al target previsto, rimuovi eventuali AAAA errati se esistono, e lascia tempo a SSL dopo che il DNS è stabile.

Come verificare ogni passo (senza indovinare)

Una buona risoluzione dei problemi è soprattutto confronto: ciò che vedi vs ciò che ti aspetti. Non fare affidamento su “si apre sul mio telefono”. Usa controlli ripetibili.

Controlla le risposte DNS rispetto al target atteso

Usa uno strumento di lookup DNS (come nslookup o dig) e conferma che il valore restituito corrisponda a quello che intendevi (un IP per A o AAAA, un hostname per CNAME, un token per TXT).

# Apex (root) domain
dig example.com A

dig example.com AAAA

# www subdomain
dig www.example.com CNAME

# TXT (spesso usato per verifica)
dig example.com TXT

Controlla entrambi i nomi che potresti usare: l'apex (example.com) e www (www.example.com). È comune che uno sia corretto mentre l'altro punti ancora a qualcosa di vecchio.

Controlla il comportamento del browser (HTTP, HTTPS e redirect)

Apri sia http:// che https:// per l'apex e per www. Vuoi un dominio “home” chiaro e un redirect pulito.

• Scegli un dominio canonico (o l'apex o www) e reindirizza l'altro verso quello.
• Evita redirect ping‑pong (A reindirizza a B, poi B reindirizza di nuovo ad A).
• Se HTTP funziona ma HTTPS fallisce, SSL è o ancora in emissione o il DNS punta ancora a un posto inatteso.

Se i risultati differiscono per rete, è probabile che tu stia vedendo caching o propagazione. Tieni un piccolo registro: cosa hai cambiato, dove lo hai fatto, l'orario e cosa hai osservato.

Errori comuni che fanno perdere ore

La maggior parte dei problemi DNS e SSL non sono misteri. Sono piccoli errori che ti portano a controllare la cosa sbagliata o a cambiare le cose troppo velocemente per ottenere una lettura chiara.

Il più comune spreco di tempo è modificare il DNS in due posti. Succede spesso dopo aver cambiato nameserver: aggiorni i record al registrar, ma il DNS è ospitato altrove (o viceversa). Tutto sembra corretto in una dashboard, eppure nulla cambia pubblicamente.

Un altro errore classico è tentare di mettere un CNAME sul dominio root con un provider che non lo supporta. Potresti aver bisogno di un record A, o di un record ALIAS o ANAME se il tuo provider DNS li offre.

L'IPv6 può anche creare problemi. Lasciare un vecchio record AAAA può mandare alcuni visitatori al server sbagliato mentre altri arrivano correttamente via IPv4.

Fai attenzione ai record “just in case”. Più record A possono comportarsi come un bilanciamento accidentale se un target è sbagliato, specialmente quando punti un dominio personalizzato a un'app ospitata.

Una regola finale: smetti di resettare l'orologio.

• Non cambiare i record ogni pochi minuti.
• Non mescolare target vecchi e nuovi contemporaneamente.
• Aspetta che le cache si stabilizzino prima di giudicare i risultati.

Piccoli cambi calmi battono continue modifiche affrettate.

Un esempio realistico: www funziona ma il dominio root no

Lanci un'app nuova e configuri sia example.com sia www.example.com. Pochi minuti dopo, www.example.com si apre correttamente, ma il dominio root mostra un errore DNS, carica un sito vecchio o HTTPS resta in sospeso. Questo pattern è comune e di solito ha una causa semplice.

Inizia con la domanda noiosa: stai modificando il DNS nel posto giusto? Se il dominio è registrato presso una società ma il DNS è ospitato altrove, puoi cambiare i record tutto il giorno e nulla succederà. Controlla prima i nameserver, poi apri il pannello DNS del provider a cui quei nameserver puntano.

Poi, confronta i due hostname. www è tipicamente un CNAME. Il dominio root è più complicato: molti provider non permettono un CNAME all'apex, quindi spesso necessita di un record A verso un IP, o di un record ALIAS/ANAME se supportato.

Un percorso decisionale che funziona nella pratica:

• Nameserver sbagliati o inaspettati? Correggi prima quelli.
• Nameserver corretti ma example.com non ha record (o punta altrove)? Correggi il record apex.
• I record sembrano giusti ma il comportamento varia per dispositivo o rete? Aspetta la propagazione e svuota le cache.
• Il DNS risolve correttamente ma HTTPS fallisce o è bloccato? SSL sta aspettando un DNS coerente.

Lo stato finale corretto è noioso: sia example.com che www.example.com portano alla stessa app, uno è canonico (l'altro reindirizza), e HTTPS è valido.

Checklist rapida che puoi eseguire in 5 minuti

Quando una configurazione dominio fallisce, molte soluzioni derivano da pochi controlli rapidi. Esegui questi prima di cambiare altro.

• Conferma che stai modificando il DNS nel posto giusto (abbina la tua dashboard ai nameserver autorevoli del dominio).
• Verifica che hostname e target siano esatti (nessun sottodominio mancante, nessun punto in più). Confronta il tipo di record (A, AAAA, CNAME, TXT) con quello che il tuo host si aspetta.
• Rimuovi conflitti (CNAME più altri record sullo stesso nome, o vecchi record A o AAAA che non servono più).
• Controlla da due punti di vista (dati mobili e Wi‑Fi). Se uno funziona e l'altro no, è di solito caching o propagazione.
• Rispetta il TTL. Se il TTL è 300 secondi, aspetta 5–10 minuti prima di giudicare. Se il TTL è 3600, aspetta circa un'ora.

Dopo che il DNS è chiaramente corretto, controlla SSL. Molte piattaforme emettono il certificato solo dopo che riescono a risolvere il dominio verso il target giusto in modo coerente. Se controlli troppo presto, puoi scambiare un ritardo normale per un errore reale.

Se stai aggiungendo un dominio personalizzato a un'app distribuita su Koder.ai, considera la schermata di configurazione dominio dell'app come riferimento per il target DNS atteso, poi ricontrolla lo stato solo dopo che il DNS ha avuto tempo per propagarsi.

Passi successivi: rendi ripetibile la configurazione dominio a ogni lancio

Il modo più veloce per evitare di ripetere errori DNS e SSL è tenere una breve “nota di setup dominio” per ogni progetto. È un runbook riutilizzabile che puoi copiare la prossima volta che lanci.

Un semplice modello di nota per la configurazione dominio

Tienilo nei documenti di progetto e compilalo prima di toccare il DNS:

• Domini e hostname (root, www e qualsiasi sottodominio)
• Tipi di record e target previsti (A, CNAME, TXT) e da dove provengono
• Dove si modifica il DNS (quale provider) e i nameserver attivi
• Aspettative SSL (chi lo emette, cosa significa “pronto”)
• Passi di verifica che eseguirai (strumento e risultato atteso)

Durante il lancio, assegna una persona come proprietario del DNS. I problemi DNS avvengono più spesso quando due persone “sistemano” cose diverse contemporaneamente (per esempio, una cambia nameserver mentre un'altra modifica i record).

Sul lato hosting, pianifica inversioni sicure. Se la tua piattaforma supporta snapshot o rollback, fai uno snapshot prima di cambiare il routing così puoi tornare rapidamente all'ultimo stato funzionante. Se costruisci su Koder.ai, puoi usare Planning Mode per annotare i passaggi del dominio che farai, applicarli in ordine e ripristinare se un cambiamento rompe la produzione.

Quando andare oltre e a chi rivolgersi

Se hai confermato che il DNS è corretto e vedi ancora errori, smetti di indovinare e scala con prove:

• Il registrar mostra nameserver bloccati o non riesci a cambiarli
• Le modifiche DNS non compaiono da nessuna parte dopo la finestra TTL prevista
• SSL continua a fallire molto dopo che il DNS risolve correttamente (pensa a ore, non minuti)
• Vedi record in conflitto che non puoi rimuovere (bug dell'interfaccia provider o DNS diviso)

Quando fai escalation, includi l'hostname, i record previsti, i risultati dei resolver attuali e i timestamp. Questo trasforma un lungo scambio in una soluzione rapida.