# Résoudre les problèmes de domaines et d'URLs

> Les symptômes fréquents — certificat en attente, DNS non propagé, route en échec, connexion refusée — avec leur cause et leur solution.

Cette page part de ce que vous voyez dans la console ou dans votre navigateur. Les messages sont cités tels qu'ils s'affichent.

## Symptômes

- [Le certificat reste en attente](#le-certificat-reste-en-attente)
- [La route passe en FAILED](#la-route-passe-en-failed)
- [Le nom d'hôte ne résout pas](#le-nom-dhôte-ne-résout-pas)
- [Les identifiants DNS restent en échec](#les-identifiants-dns-restent-en-échec)
- [Impossible de créer le domaine.](#impossible-de-créer-le-domaine)
- [Impossible de sauvegarder la route.](#impossible-de-sauvegarder-la-route)
- [Impossible d'instancier cette route.](#impossible-dinstancier-cette-route)
- [Le service répond 404 sur un sous-chemin](#le-service-répond-404-sur-un-sous-chemin)
- [La connexion échoue sur un nouveau nom d'hôte](#la-connexion-échoue-sur-un-nouveau-nom-dhôte)
- [Le domaine ne peut pas être supprimé](#le-domaine-ne-peut-pas-être-supprimé)

## Le certificat reste en attente

La route reste en `PROVISIONING` et le navigateur affiche une erreur de certificat sur le nom d'hôte.

**Cause** : Let's Encrypt ne délivre le certificat qu'une fois le nom d'hôte résolu vers la gateway. Tant que l'enregistrement DNS n'est pas propagé, ou si un autre enregistrement occupe le même nom, le défi HTTP-01 échoue.

**Solution** :

1. Vérifiez que le nom résout vers la gateway :

   ```bash
   dig +short app.staging.exemple.fr
   ```

   Vous devez obtenir le nom ou l'adresse de la gateway, pas une ancienne adresse.
2. Si un enregistrement créé à la main occupe le même nom chez votre fournisseur, supprimez-le.
3. Attendez la propagation, puis cliquez sur **Actualiser** dans l'onglet **URLs & IAM**. La plateforme relance d'elle-même l'émission après 10 minutes, puis après 30 minutes.

**Pour vérifier** : la colonne **STATUS** passe à `PROVISIONED` et `curl -I https://<nom>` répond sans erreur de certificat.

## La route passe en FAILED

La colonne **STATUS** affiche `FAILED`.

**Cause** : le certificat n'a pas pu être obtenu après trois tentatives, ou aucune gateway n'était disponible pour l'environnement.

**Solution** :

1. Corrigez la cause DNS, comme pour [un certificat en attente](#le-certificat-reste-en-attente).
2. Dans **Instances de routes dans l'environnement**, cliquez sur **Supprimer route** (ou **Supprimer URL (toutes les routes)** si le nom d'hôte porte plusieurs routes), puis confirmez.
3. Quand la route a disparu de la liste, instanciez-la de nouveau depuis **Routes d'architecture manquantes dans l'environnement**. Un nouveau certificat est demandé.

**Pour vérifier** : la route repasse par `PENDING`, `PROVISIONING`, puis `PROVISIONED`.

## Le nom d'hôte ne résout pas

`dig` ne renvoie rien pour le nom d'hôte alors que la route est instanciée.

**Cause** : l'enregistrement n'a pas pu être écrit chez votre fournisseur : identifiants invalides ou expirés, clé sans droit sur la zone, ou zone absente chez le fournisseur.

**Solution** :

1. Vérifiez chez votre fournisseur que la zone indiquée dans **Zone DNS** existe et que la clé y a accès en écriture.
2. Sur la page **Domaines**, ouvrez le menu du domaine, cliquez sur **Mettre à jour les credentials** et enregistrez une clé valide.
3. Retirez puis instanciez de nouveau la route.

**Pour vérifier** : l'enregistrement apparaît dans la zone chez votre fournisseur, puis `dig` renvoie la gateway.

## Les identifiants DNS restent en échec

La colonne **Credentials DNS** affiche **Échec de la configuration**, ou **La vérification prend plus de temps que prévu.** pendant l'enregistrement.

**Cause** : les identifiants n'ont pas pu être mis à disposition du moteur DNS. Le motif s'affiche sous le badge.

**Solution** : ouvrez le menu du domaine, cliquez sur **Reconfigurer**, saisissez de nouveau tous les champs, puis cliquez sur **Enregistrer**. Un message **Champs requis manquants : …** signale un champ oublié.

**Pour vérifier** : le badge passe à **Credentials actifs**.

## Impossible de créer le domaine.

Le message s'affiche à l'étape 1/2 de **Ajouter un domaine personnalisé**.

**Cause** : le nom de domaine est déjà déclaré sur la plateforme, par votre application ou par une autre. Un nom de domaine ne peut appartenir qu'à une seule app.

**Solution** : vérifiez la liste **Domaines personnalisés** et la carte **Domaines plateforme**. Si le domaine est déclaré par une autre de vos applications, supprimez-le d'abord de celle-ci. Sinon, contactez Wakastart.

## Impossible de sauvegarder la route.

Le message s'affiche à l'enregistrement du dialogue **Nouvelle route** ou **Modifier la route**.

**Cause** : le champ **Port (optionnel)** est renseigné, ou une route existe déjà pour ce chemin sur cette URL.

**Solution** : videz **Port (optionnel)** (le port vient de la définition du service), vérifiez que le chemin n'est pas déjà utilisé sur l'URL, puis enregistrez.

## Impossible d'instancier cette route.

Le message s'affiche après **Instancier** dans l'onglet **URLs & IAM**.

**Cause** : la route est déjà instanciée dans l'environnement (la liste n'était pas à jour), ou aucune gateway n'est disponible pour l'environnement.

**Solution** : cliquez sur **Actualiser**. Si la route figure dans **Instances de routes dans l'environnement**, elle est déjà en ligne. Sinon, réessayez dans quelques minutes, puis contactez Wakastart si le message persiste.

## Le service répond 404 sur un sous-chemin

`https://app.exemple.fr/api/commandes` renvoie une page 404 de votre service, alors que la route `/api` est `PROVISIONED`.

**Cause** : le chemin est transmis tel quel. Le service reçoit `/api/commandes`, pas `/commandes`.

**Solution** : configurez votre service pour qu'il réponde sous le préfixe `/api` (préfixe global de votre framework), ou exposez-le sur sa propre URL avec la route `/`.

## La connexion échoue sur un nouveau nom d'hôte

Le site s'affiche, mais la connexion n'aboutit pas : Discovery ne trouve pas de realm, ou Keycloak refuse l'adresse de retour.

**Cause** : le nom d'hôte n'a pas d'hôte IAM, ou Keycloak n'a pas encore reçu la nouvelle adresse de retour.

**Solution** : dans la section **Hôtes IAM** de l'onglet **URLs & IAM**, cliquez sur **Resynchroniser IAM** (niveau Administrateur réseau requis). Vérifiez ensuite que le nom figure dans la liste.

**Pour vérifier** : `POST /discover/start-login` avec ce `host` renvoie un `keycloakUrl` (voir [Gérer les hôtes IAM](/v1.0/domaines-et-urls/gerer-les-hotes-iam#vérifier-le-résultat)).

## Le domaine ne peut pas être supprimé

L'action **Supprimer** est grisée avec la mention **URLs actives**.

**Cause** : des URLs, un domaine racine ou des redirections utilisent encore le domaine.

**Solution** : retirez-les des environnements, supprimez-les de l'architecture, puis supprimez le domaine.

## Toujours bloqué ?

Contactez le support Wakastart avec :

- le nom de l'application et de l'environnement ;
- le nom d'hôte concerné et le statut affiché ;
- l'heure de l'instanciation ;
- le message exact affiché par la console ;
- la sortie de `dig +short <nom>` et de `curl -I https://<nom>`.
