---
title: Vérification et dépannage
slug: oip-next/v4/verification-depannage
icon: {"lucideIcon":"📘"}
createdAt: 2026-08-18T09:10:00.000Z
---

# Vue d'ensemble

Cette page permet de contrôler qu'un projet fraîchement installé fonctionne de bout en bout, puis de diagnostiquer les erreurs les plus fréquemment rencontrées lors des premiers pas.

Elle est organisée par symptôme : à chaque symptôme correspond une cause probable et une correction.

# Checklist de vérification

| # | Contrôle                         | Attendu                                                                       |
| - | -------------------------------- | ----------------------------------------------------------------------------- |
| 1 | `docker compose ps`              | Les services annexes sont démarrés.                                           |
| 2 | `npm run migrate:dev`            | Les migrations en attente sont appliquées sans erreur.                        |
| 3 | `npm run start-server:dev`       | Le serveur Express démarre et journalise sa version.                          |
| 4 | `npm run front:dev`              | Le client Vite est servi sur le port `8000`.                                  |
| 5 | Décrochage                       | La première vue s'affiche dans le navigateur.                                 |
| 6 | `npm run entities:gen`           | La commande se termine sans erreur et ne produit pas de migration inattendue. |
| 7 | `npm run views:gen`              | La commande valide les transitions de chaque vue.                             |
| 8 | `npm run lint` et `npm run test` | Aucune erreur.                                                                |

# Erreurs courantes

## Installation et initialisation

| Symptôme                                                     | Cause probable                                          | Correction                                                                   |
| ------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `npm install` échoue sur une erreur d'authentification.      | Le registre npm privé `@fasstech` n'est pas accessible. | Vérifiez l'authentification déclarée dans le fichier `.npmrc`.               |
| Le clone du modèle de projet échoue.                         | Absence de droits sur `fasst/fasst-oip-starter`.        | Faites vérifier votre accès au dépôt, et l'existence de la branche `v4`.     |
| `docker compose up -d` échoue au téléchargement d'une image. | Absence de droits sur les images `fasstech/*`.          | Authentifiez-vous auprès du registre Docker, puis relancez la commande.      |
| Les commandes distantes d'OIP Tools échouent.                | `OIP_TOOLS_CLIENT_SECRET` absente ou invalide.          | Renseignez la variable dans le fichier `.env` avant de relancer la commande. |

## Génération de code et migrations

| Symptôme                                                                                | Cause probable                                                           | Correction                                                                                                         |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `views:gen` s'arrête sur une erreur de transition.                                      | Le fichier de transition d'une vue est absent, mal nommé ou invalide.    | Créez `transitions/<viewId>.mjs` : le nom du fichier doit correspondre exactement au `viewId` de la vue.           |
| `migrate:dev` échoue en signalant une migration manquante.                              | Un fichier de migration déjà exécuté a été supprimé, renommé ou modifié. | Restaurez le fichier depuis l'historique Git. Toute correction passe par une nouvelle migration.                   |
| Une entité déclarée dans la configuration n'existe pas en base.                         | La migration produite par `entities:gen` n'a pas été appliquée.          | Exécutez `npm run migrate:dev`.                                                                                    |
| Une modification apportée à un fichier du répertoire `entities/` ou `views/` a disparu. | Le fichier est généré et a été réécrit.                                  | Modifiez la configuration source, puis régénérez. Voir « [Code généré](./004_conventions/004_generated_code.md) ». |

## Démarrage du serveur

| Symptôme                                                  | Cause probable                                                    | Correction                                                                             |
| --------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Le serveur s'arrête immédiatement au démarrage.           | Une variable d'environnement obligatoire est absente ou invalide. | Le journal indique la variable fautive. Comparez `.env` et `.env.dist`, puis corrigez. |
| Le serveur démarre mais aucune donnée n'est persistée.    | `OIP_API_URL` ou `OIP_API_KEY` incorrecte.                        | Vérifiez que l'URL pointe bien vers le service OIP Headless démarré localement.        |
| Les erreurs GraphQL retournées au client sont génériques. | `NODE_ENV` vaut `production`.                                     | Comportement attendu. En développement, positionnez une autre valeur.                  |

## Décrochage et session

| Symptôme                                                    | Cause probable                                           | Correction                                                                                              |
| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Le décrochage échoue alors qu'aucun jeton n'est fourni.     | `SECURE_SESSION` vaut `true`.                            | Fournissez un jeton en paramètre d'URL, ou positionnez `SECURE_SESSION=false` en développement.         |
| Le jeton est refusé.                                        | Jeton expiré, ou `SESSION_SERVICE_URL` incorrecte.       | Générez un nouveau jeton et vérifiez l'URL du service de sessions.                                      |
| La session est perdue à chaque requête.                     | Le cookie de session n'est pas transmis.                 | `SECURE_COOKIE=true` impose l'usage d'HTTPS : positionnez la variable à `false` en développement local. |
| Le magasin de sessions est inaccessible au démarrage.       | La base désignée par `SESSION_STORE_URL` n'existe pas.   | Créez la base de données dédiée aux sessions.                                                           |
| Le parcours redémarre systématiquement sur la première vue. | `resolveFirstView` ignore le `viewId` reçu en paramètre. | Retournez le `viewId` reçu lorsqu'il est non nul, afin de reprendre le parcours où il s'était arrêté.   |

## Client

| Symptôme                                                               | Cause probable                                                                      | Correction                                                                                           |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Le client n'atteint pas le serveur dans un déploiement multi-origines. | `SERVER_URL` non définie, ou variable `__SERVER_URL__` absente de `vite.config.js`. | Déclarez la variable d'environnement et son équivalent dans la section `define` de `vite.config.js`. |
| Les appels GraphQL sont rejetés par le navigateur.                     | Configuration CORS trop restrictive.                                                | Ajustez `corsOptions` dans la configuration du serveur.                                              |
| L'authentification client échoue.                                      | `CLIENT_ID`, `CLIENT_SECRET` ou `API_KEYS` incohérents.                             | `API_KEYS` doit valoir `CLIENT_ID:CLIENT_SECRET`.                                                    |

## Tâches asynchrones

| Symptôme                                       | Cause probable                             | Correction                                                                                           |
| ---------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Une tâche est programmée mais jamais exécutée. | Le consommateur AMQP n'est pas enregistré. | Enregistrez un consommateur sur la file `<OAV_ID>.events` avec `handleTask` dans `server/index.mjs`. |
| Aucune notification n'est reçue côté client.   | Connexion RabbitMQ invalide.               | Vérifiez `RABBIT_MQ_HOST`, `RABBIT_MQ_USER`, `RABBIT_MQ_PASSWORD` et `RABBIT_MQ_VHOST`.              |
| La tâche reste dans l'état `executing`.        | Le processus enfant ne se termine pas.     | Terminez explicitement le processus par `process.exit(0)` ou `process.exit(1)`.                      |

# Journalisation

Le niveau de journalisation est piloté par la variable `LOGGER_LEVEL`. L'implémentation fournie par défaut propose quatre niveaux :

| Niveau    | Usage                                                     |
| --------- | --------------------------------------------------------- |
| `ERROR`   | Valeur par défaut : seules les erreurs sont journalisées. |
| `WARNING` | Ajoute les avertissements.                                |
| `INFO`    | Ajoute les évènements de fonctionnement nominal.          |
| `DEBUG`   | Ajoute le détail utile au diagnostic.                     |

Consultez les journaux des services annexes :

```shell
docker compose logs -f
```

:::BlockQuote
**\[info]** En phase de diagnostic, positionnez `LOGGER_LEVEL=DEBUG` dans le fichier `.env`, puis redémarrez le serveur.
:::

# Repartir d'un environnement propre

En développement uniquement, il est parfois plus rapide de réinitialiser complètement les services annexes et leurs données :

```shell
docker compose down -v
docker compose up -d
npm run migrate:dev
```

:::BlockQuote
**\[warn]** L'option `-v` supprime les volumes, donc l'intégralité des données persistées. Cette procédure ne doit jamais être appliquée à un environnement partagé.
:::

# Résumé

- Une installation saine se vérifie en huit contrôles, du démarrage des services à l'exécution des tests ;
- `LOGGER_LEVEL=DEBUG` et `docker compose logs -f` sont les deux premiers réflexes de diagnostic.
