Résolution des problèmes

Référence des symptômes, causes et solutions aux erreurs rencontrées par les participants pendant ce laboratoire, regroupées selon l’étape où elles apparaissent.

Chaque entrée ci-dessous correspond à une erreur réelle : les onze documentées dans les fichiers README des différentes parties du laboratoire, auxquelles s’ajoutent cinq erreurs détectées lors de la création et du test de cet atelier. Repérez votre symptôme, lisez sa cause et appliquez la solution. Si aucune entrée ne correspond, les sections ## Common failures du parcours formateur décrivent plus en détail les problèmes que peut rencontrer l’animateur dans chaque module. Adressez-vous ensuite à votre architecte de solutions.

Chaîne d’outils et préparation

Échec de `dbt` avec une erreur d’importation `mashumaro`, ou installation impossible

Symptôme - l’installation de dbt-snowflake ou de dbt-clickhouse échoue, ou dbt génère une erreur d’importation mentionnant mashumaro, sans rapport évident avec votre version de Python.
Cause - dbt-snowflake et dbt-clickhouse nécessitent tous deux Python 3.11, 3.12 ou 3.13. Python 3.14 et les versions ultérieures rendent incompatible leur dépendance commune mashumaro. L’erreur apparaît généralement dans un module sans rapport avec la faute initiale.
Solution - installez Python 3.13 à côté de la version système (par exemple avec brew install python@3.13), puis recréez explicitement l’environnement virtuel avec cet interpréteur : python3.13 -m venv .venv.

Environnement source Snowflake

Échec de `terraform init` avec une erreur de fournisseur

Symptôme - terraform init échoue dans workshop_public/snowflake_migration_lab/01-setup-snowflake/ lors de la résolution d’un fournisseur.
Cause - le binaire Terraform est ancien ou le registre Terraform n’est pas accessible par le réseau.
Solution - utilisez Terraform >= 1.6 et vérifiez l’accès à Internet vers le registre.

Connexion `snowsql` refusée

Symptôme - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} refuse la connexion.
Cause - SNOWFLAKE_ORG ou SNOWFLAKE_ACCOUNT est incorrect.
Solution - vérifiez à nouveau les deux valeurs par rapport au compte créé, puis réessayez la même commande snowsql.

Échec de `dbt run` avec `relation not found`

Symptôme - dbt run signale, dans le projet dbt de la première partie, une relation inexistante.
Cause - la structure de la base de données n’a jamais été créée.
Solution - exécutez d’abord ./setup.sh --skip-seed, puis vérifiez que profiles.yml pointe vers NYC_TAXI_DB.

Superset affiche `connection refused`

Symptôme - l’interface Superset de la première partie refuse la connexion juste après docker-compose up.
Cause - l’initialisation de Superset prend environ 60 secondes.
Solution - attendez 60 secondes et réessayez. Si l’erreur persiste, consultez docker logs nyc_taxi_superset.

Le chargement des données prend plus de temps que prévu

Symptôme - l’étape de chargement dans workshop_public/snowflake_migration_lab/01-setup-snowflake/ semble bloquée.
Cause - ce comportement est normal pour Snowflake à cette échelle, il ne s’agit pas d’un blocage. L’insertion TABLE(GENERATOR) qui produit 50 millions de lignes prend environ 10 à 12 minutes. La commande UPDATE suivante, qui renseigne la colonne VARIANT TRIP_METADATA sur ces 50 millions de lignes, prend encore 15 à 20 minutes sur un warehouse SMALL.
Solution - laissez l’opération se terminer. Aucune de ces étapes n’est interactive et il n’y a rien à relancer.

Provisionnement de ClickHouse Cloud et migration des données

Échec de l’authentification Terraform avec 401 Unauthorized

Symptôme - l’application Terraform dans workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ échoue avec 401 Unauthorized.
Cause - CLICKHOUSE_TOKEN_KEY ou CLICKHOUSE_TOKEN_SECRET est incorrect, ou la clé ne dispose pas de l’autorisation requise.
Solution - recréez la paire de clés depuis l’interface de ClickHouse Cloud sous Settings -> API keys, et assurez-vous qu’elle possède la portée Admin.

Le script de migration échoue en cours d’exécution

Symptôme - scripts/02_migrate_trips.py s’interrompt pendant la copie des 50 millions de lignes.
Cause - des incidents temporaires de réseau ou de warehouse surviennent pendant un transfert de longue durée.
Solution - relancez le script avec --resume. Il utilise comme repère le max(pickup_at) déjà présent dans ClickHouse et ignore les lignes déjà chargées :
```
python scripts/02_migrate_trips.py --resume
```

Erreur de connexion du script de migration

Symptôme - le script de migration ne parvient pas à joindre Snowflake ou ClickHouse.
Cause - une ou plusieurs variables d’environnement Snowflake ou ClickHouse ne sont pas définies dans le shell actuel.
Solution - vérifiez-les, puis rechargez les fichiers d’état avant de réessayer :
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
Exécutez d’abord source .env && source .clickhouse_state, puis réessayez.

Échec de `dbt run` avec `Connection refused` ou `Unknown host`

Symptôme - dbt run, exécuté sur le projet ClickHouse, ne parvient pas à résoudre ou à joindre un hôte.
Cause - CLICKHOUSE_HOST n’est pas défini dans le shell actuel.
Solution - exécutez source .clickhouse_state depuis le répertoire du module, puis relancez dbt run.

Échec de `dbt` avec `Could not find profile named 'nyc_taxi_ch'`

Symptôme - dbt debug ou dbt run échoue immédiatement avec une erreur de profil manquant dans workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch.
Cause - le profil dbt de ClickHouse n’a jamais été ajouté à ~/.dbt/profiles.yml.
Solution - ouvrez workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example et fusionnez son bloc nyc_taxi_ch: avec votre fichier ~/.dbt/profiles.yml existant, sous forme de second profil de premier niveau. N’écrasez pas le fichier : cela supprimerait le profil nyc_taxi: du module 01 et interromprait sa boucle d’actualisation de l’étape 4. Consultez 03 Provisionnement et migration, qui décrit cette fusion en détail.

dbt sur ClickHouse

`analytics.agg_hourly_zone_trips` est vide après l’exécution de dbt

Symptôme - après le dbt run du module 04, analytics.agg_hourly_zone_trips ne contient aucune ligne et tous les graphiques de tableau de bord qui s’appuient dessus sont vides.
Cause - ce résultat est attendu, il ne s’agit pas d’une erreur. Le filtre incrémentiel du modèle est WHERE pickup_at >= now() - INTERVAL 2 HOUR, qui ne correspond qu’aux lignes écrites par le producteur de trajets en direct. Toutes les lignes déplacées par le script de migration sont historiques ; aucune ne se trouve donc dans cette fenêtre de deux heures.
Solution - aucune correction n’est nécessaire. Zéro est ici la bonne valeur. La table se remplit lorsque le producteur écrit directement dans ClickHouse après l’étape de bascule de 05 Benchmark et bascule.

Tableaux de bord et benchmark

Superset affiche 403 Forbidden

Symptôme - l’interface Superset renvoie 403 Forbidden en cours de module.
Cause - le cookie de session a expiré.
Solution - déconnectez-vous, reconnectez-vous sur http://localhost:8088, puis relancez bash superset/add_clickhouse_connection.sh.

Le benchmark affiche `N/A` pour Q7

Symptôme - le fichier CSV produit par run_benchmark.sh contient N/A au lieu d’une accélération pour la requête 7.
Cause - le script de benchmark n’a pas pu se connecter à ClickHouse.
Solution - vérifiez que CLICKHOUSE_HOST est défini (source .clickhouse_state) et que le service fonctionne, puis relancez le benchmark.

Un tableau de bord Superset importé ne se connecte pas à ClickHouse

Symptôme - les tableaux de bord importés dans Superset se chargent, mais leurs graphiques ne peuvent pas joindre ClickHouse.
Cause - l’hôte du fichier ZIP d’exportation enregistré a été remplacé par your-instance.clickhouse.cloud. Le script add_clickhouse_connection.sh remplace cette valeur par l’URI réelle issue de .env avant l’importation, ce que ne fait pas un import manuel dans l’interface Superset.
Solution - utilisez bash superset/add_clickhouse_connection.sh au lieu d’un import manuel, ou modifiez ensuite la connexion afin d’utiliser la valeur réelle de CLICKHOUSE_HOST et vos identifiants.

Bascule et parité

Le contrôle de parité échoue, ou la bascule semble perdre des lignes

Symptôme - le contrôle du nombre de lignes du module 05 échoue, ou la bascule semble avoir perdu des données.
Cause - la passe de rattrapage avec --resume a été omise. Le producteur Snowflake écrit en continu pendant les modules 01 à 05. La migration du module 03 n’a donc capturé qu’un préfixe des données ; la fin demeure uniquement dans Snowflake jusqu’au rattrapage. Arrêter le producteur Snowflake trop tôt, par exemple juste après le module 01, détruit silencieusement la démonstration de bascule de ce module, car il ne reste alors plus aucune donnée à rattraper.
Solution - exécutez la passe de rattrapage avant de contrôler la parité. Elle ne déplace que les lignes manquantes et prend de quelques secondes à quelques minutes, pas les 40 à 50 minutes initiales :
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```