Dépannage

Une référence classée par zone d’apparition, indiquant le symptôme, la cause et la correction de chaque problème rencontré pendant la création et les tests de cet atelier.

Les commandes de cette page utilisent les valeurs enregistrées dans .env.workshop.

Chaque entrée ci-dessous correspond à une panne réellement rencontrée pendant la création et les tests de cet atelier. Repérez votre symptôme, comprenez sa cause et appliquez la correction. Si rien ne correspond, confiez le problème à votre agent de programmation : le guide pour suivre l’atelier en autonomie contient une instruction prête à coller qui en fera votre formateur.

Windows et WSL 2

`wsl --install` est indisponible ou affiche seulement l’aide

Symptôme — PowerShell en tant qu’administrateur ne reconnaît pas wsl --install ou affiche l’aide au lieu d’installer Ubuntu.
Cause — la version de Windows est antérieure au minimum requis pour l’atelier, des mises à jour en attente n’ont pas été appliquées ou une politique de l’entreprise désactive WSL.
Correction — exécutez Windows Update et vérifiez que vous utilisez Windows 11 ou Windows 10 version 2004 (build 19041) ou ultérieure. Redémarrez, puis suivez les étapes d’installation manuelle de WSL de Microsoft. Sur une machine gérée, un administrateur doit autoriser les fonctionnalités Windows nécessaires.

Une commande n’est « pas reconnue » dans PowerShell

Symptôme — PowerShell rejette ./preflight.sh, export, source ou une autre commande Bash de l’atelier.
Cause — la configuration Windows n’utilise PowerShell que pour l’amorçage WSL expressément indiqué. Les commandes de l’atelier s’exécutent dans Ubuntu sur WSL 2.
Correction — ouvrez Ubuntu depuis le menu Start, revenez dans le répertoire de l’application et exécutez-y la vérification préalable :
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

Le dépôt se trouve sous `/mnt/c`

Symptôme — les montages de liaison Docker sont lents, les scripts rencontrent des problèmes d’autorisation ou de fins de ligne, ou le chemin du dépôt commence par /mnt/c/Users/....
Cause — le dépôt a été cloné sur le système de fichiers Windows au lieu du système de fichiers Linux de WSL.

Correction — ne conservez l’ancienne copie que si vous devez récupérer du travail non versionné. Sinon, ouvrez Ubuntu et clonez une copie propre dans votre répertoire personnel Linux :

cd ~
git config --global core.autocrlf input
git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

Ubuntu s’exécute avec WSL 1

Symptôme — wsl --list --verbose affiche Ubuntu avec VERSION 1, ou Docker Desktop ne parvient pas à s’intégrer à la distribution.
Cause — la distribution est antérieure à WSL 2 ou a été installée alors que WSL 1 était la version par défaut.
Correction — ouvrez PowerShell as Administrator, convertissez la distribution, puis rouvrez Ubuntu :
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

`docker` est indisponible dans Ubuntu

Symptôme — Docker Desktop fonctionne, mais Ubuntu indique docker: command not found ou ne peut pas joindre le démon.
Cause — le moteur WSL de Docker Desktop ou l’intégration Ubuntu est désactivé.
Correction — activez Docker Desktop -> Settings -> General -> Use the WSL 2 based engine et Resources -> WSL Integration -> Ubuntu, appliquez la modification, puis exécutez wsl --shutdown dans PowerShell et rouvrez Ubuntu. docker version doit alors afficher les sections Client et Server.

WSL ou Docker dispose de moins de 6 Go de mémoire

Symptôme — la vérification préalable signale un manque de mémoire, ou docker info --format 'Docker memory: {{.MemTotal}} bytes' affiche moins de 6442450944 octets.
Cause — le back-end WSL 2 de Docker Desktop utilise la limite de mémoire de la machine virtuelle WSL.
Correction — fermez Docker Desktop, ouvrez PowerShell et définissez une limite WSL de 8 Go :
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Démarrez Docker Desktop et rouvrez Ubuntu. Réexécutez la commande docker info et la vérification préalable.

Un script signale `/usr/bin/env: 'bash\r': No such file or directory`

Symptôme — un fichier .sh échoue immédiatement et l’erreur contient bash\r ou ^M.
Cause — les fins de ligne CRLF de Windows ont remplacé les fins de ligne LF requises par le dépôt.
Correction — dans Ubuntu, définissez la politique Git pour WSL et rétablissez un clone propre :
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
Examinez git status avant de supprimer ou de versionner quoi que ce soit. Si le clone ne contient aucun travail à conserver, un nouveau clone sous ~/ClickHouse_Demos est la solution de récupération la plus sûre.

OAuth n’ouvre pas le navigateur Windows

Symptôme — une connexion MCP affiche une URL, mais aucune fenêtre du navigateur ne s’ouvre.
Cause — l’agent de programmation s’exécute dans WSL et le transfert vers le navigateur est indisponible ou bloqué par une politique de l’entreprise.
Correction — copiez l’URL de connexion complète depuis Ubuntu et collez-la dans le navigateur Windows habituel. Terminez-y l’autorisation, puis revenez au terminal Ubuntu.

Docker

Les conteneurs restent à l’état « Created » sans jamais démarrer

Symptôme — docker info répond correctement, mais docker compose ... up laisse les conteneurs à l’état Created et aucun ne devient opérationnel.
Cause — le moteur Docker est bloqué : le démon répond, mais ne parvient pas réellement à lancer un conteneur. Ce problème a été observé avec OrbStack lors d’un démarrage en direct.
Correction — redémarrez votre moteur Docker (Docker Desktop, OrbStack ou Colima) et attendez qu’il indique Running, puis redémarrez la pile. Depuis n’importe quel emplacement du dépôt cloné, exécutez cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh ; ce script détecte le problème avant le démarrage de la pile en lançant un conteneur jetable comme test.

Erreur « port is already allocated » au démarrage

Symptôme — docker compose ... up échoue avec Bind for 0.0.0.0:8080 failed: port is already allocated (ou :8000).
Cause — un autre processus ou un ancien conteneur de l’atelier occupe déjà ce port hôte.
Correction — depuis n’importe quel emplacement du dépôt cloné, exécutez cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh. Le script identifie le détenteur du port et affiche précisément la substitution à définir, selon la convention « port de base + 20000 », par exemple set FRONTEND_HOST_PORT=28080 in .env.workshop. Les variables de substitution sont FRONTEND_HOST_PORT, BACKEND_HOST_PORT et, pour la surcouche d’observabilité, OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT. Définissez la valeur proposée, réexécutez la vérification préalable, puis démarrez la pile. Seuls les ports hôtes changent ; les ports internes aux conteneurs restent identiques, cette opération est donc sûre.

Avertissement « platform does not match »

Symptôme — Docker affiche un avertissement d’architecture incompatible, par exemple linux/amd64 face à linux/arm64, lors du téléchargement ou du démarrage.
Cause — une image a été construite pour une architecture de processeur différente de celle de votre machine, un cas courant sur Apple Silicon.
Correction — cet avertissement est sans conséquence, ce n’est pas un échec ; l’image s’exécute par émulation. Laissez l’opération se poursuivre.

ClickHouse Cloud

La première requête après une période d’inactivité est lente ou renvoie une fois une erreur 500

Symptôme — la première requête ou le premier chargement du tableau de bord après une période d’inactivité du service est lent, ou une requête renvoie une fois une erreur 500 avant de fonctionner.
Cause — un service Cloud inactif réduit sa capacité à zéro et met environ 30 secondes à se réveiller ; la première requête supporte ce coût. Le back-end autorise déjà un délai de première connexion plus long et effectue une nouvelle tentative.
Correction — réessayez simplement ou attendez environ 30 secondes. Il ne s’agit pas d’une panne. Cela compte aussi dans 07 Tester, provoquer une panne et réparer : un service en cours de réveil déclenche plus facilement l’expiration de la panne 03.

Mot de passe du service perdu

Symptôme — vous n’avez pas enregistré le mot de passe de l’utilisateur default et ne le retrouvez plus.
Cause — le mot de passe du service n’est plus affiché après la sortie du parcours de création.
Correction — ouvrez le service, accédez à ses Settings et réinitialisez le mot de passe de l’utilisateur default, puis mettez à jour CLICKHOUSE_PASSWORD dans .env.workshop. L’hôte reste accessible dans la fenêtre Connect.

Mot de passe de Postgres managé perdu

Symptôme — vous n’avez pas enregistré le mot de passe administrateur à usage unique de postgres renvoyé par clickhousectl cloud postgres create.
Cause — il n’est affiché qu’une seule fois, et les API bêta postgres get / list peuvent renvoyer un résultat vide ou FORBIDDEN même lorsque l’instance fonctionne.
Correction — exécutez clickhousectl cloud postgres reset-password <service-id>, puis utilisez le nouveau mot de passe dans .env.workshop (PGPASSWORD) et dans la connexion du ClickPipe.

ClickHouse Cloud est inaccessible

Symptôme — la vérification préalable signale l’échec du contrôle de connectivité, ou le back-end ne parvient pas à se connecter ; the command below échoue.

CLICKHOUSE_HOST=$(sed -n 's/^CLICKHOUSE_HOST=//p' .env.workshop | tail -n 1)
CLICKHOUSE_PORT=$(sed -n 's/^CLICKHOUSE_PORT=//p' .env.workshop | tail -n 1)
curl "https://$CLICKHOUSE_HOST:$CLICKHOUSE_PORT/ping"

Cause — Wi-Fi, VPN ou pare-feu ; hôte incorrect (un schéma ou un port collé dans CLICKHOUSE_HOST) ; incohérence TLS ou de port ; ou liste d’accès IP Cloud qui bloque votre adresse.
Correction — vérifiez que CLICKHOUSE_HOST contient uniquement le nom d’hôte (sans https:// ni port), que CLICKHOUSE_PORT=8443 et CLICKHOUSE_SECURE=true ; vérifiez le VPN et le pare-feu ; confirmez que la liste d’accès IP du service autorise votre adresse. La vérification préalable identifie le type précis d’échec : DNS, connexion refusée, expiration ou négociation TLS.

Le client affiche `Unknown settings: ... skipping`

Symptôme — les requêtes réussissent, mais chaque invocation affiche un avertissement de paramètre inconnu.
Cause — le client installé localement est plus récent que le serveur Cloud et envoie un paramètre que cette version du serveur ne reconnaît pas.
Correction — répétez les commandes de mise en correspondance du client indiquées à l’étape 6 du module 00. Elles lisent la version du serveur Cloud par clickhousectl et sélectionnent la version majeure et mineure correspondante du client. Ne masquez pas tous les avertissements du client avec --no-warnings.

CDC (module 03)

La création du ClickPipe signale `table realtime_trips exists and is not empty`

Symptôme — aucune ressource ClickPipe n’existe, mais sa recréation échoue parce que default.realtime_trips contient déjà des lignes.
Cause — la suppression d’un ClickPipe retire son emplacement de réplication source, mais peut laisser la table de destination. Un nouveau pipeline n’écrase pas cette table non vide.

Correction — conservez les anciennes lignes brutes sous des noms de sauvegarde horodatés, puis recréez le pipeline. Remplacez une seule fois l’espace réservé de l’identifiant du service ; ces commandes préservent aussi l’ancienne vue matérialisée lorsqu’elle existe :

CH_SERVICE_ID=<clickhouse-service-id>
BACKUP_SUFFIX=$(date -u +%Y%m%d%H%M%S)

if clickhousectl cloud service query --id "$CH_SERVICE_ID" \
  --query "EXISTS TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv" | grep -q 1; then
  clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
    RENAME TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv
    TO nyc_tlc_data.realtime_trips_to_taxi_trips_mv_backup_${BACKUP_SUFFIX}
  "
fi

clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
  RENAME TABLE default.realtime_trips
  TO default.realtime_trips_backup_${BACKUP_SUFFIX}
"

Réexécutez l’étape 3 du module 03 et attendez la nouvelle table default.realtime_trips avant de recréer la vue matérialisée canonique à l’étape 4. Ne supprimez les sauvegardes horodatées que lorsque vous êtes certain de ne plus avoir besoin de leurs données.

Le ClickPipe reste bloqué sur « Provisioning »

Symptôme — le pipeline affiche Provisioning pendant un certain temps après sa création.
Cause — l’instantané et le démarrage de l’infrastructure prennent généralement quelques minutes, mais peuvent dépasser 10 minutes même pour cette petite table.
Correction — consultez l’avancement dans la console ou avec les deux commandes clickhousectl cloud clickpipe list <clickhouse-service-id> et clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id>. Pendant les premières minutes, continuez d’attendre tant que son état ou sa valeur updatedAt progresse. S’il affiche encore Provisioning sans aucune mise à jour après 10 minutes, vérifiez que le journal de pg-trip-writer signale toujours des insertions, puis contrôlez de nouveau l’hôte, les identifiants, la publication et la correspondance des tables, et examinez l’erreur signalée par le pipeline. Ne créez ni second pipeline ni vue matérialisée tant que le premier est encore en cours de provisionnement. Si les contrôles de la source réussissent et que Cloud ne signale aucune erreur exploitable, enregistrez la sortie de get et transmettez-la au formateur ou à l’assistance ClickHouse Cloud.

Les lignes n’arrivent pas dans ClickHouse

Symptôme — le pipeline affiche Running, mais le nombre de lignes de destination n’augmente pas et le tableau de bord Ops ne bouge pas.
Cause — l’intervalle de synchronisation par défaut est d’environ 60 secondes ; un retard est donc normal. Il se peut aussi que le générateur n’insère aucune donnée ou que la publication lue par le pipeline n’existe pas.
Correction — attendez au moins 60 secondes. Vérifiez que le journal de pg-trip-writer affiche inserted N trips et soit created publication pub_taxi (votre propre instance), soit publication ... already exists (une instance managée de repli fournie par le formateur). Vérifiez que le pipeline affiche Running. Si la publication manque, le pipeline n’a rien à lire ; le générateur la crée lors de sa première exécution sur une instance dont vous êtes administrateur.

La vue matérialisée ne contient aucune ligne

Symptôme — realtime_trips se remplit, mais taxi_trips, alimentée par la vue matérialisée de CDC, reste vide.
Cause — la vue matérialisée a été créée avant la cible du ClickPipe ou ne lit pas la cible de la CLI sous default.realtime_trips.
Correction — attendez la table cible, puis copiez la commande complète de la vue matérialisée depuis le module 03, étape 4. Vérifiez d’abord la source :
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
Une vue matérialisée traite les lignes insérées après sa création ; laissez le générateur de trajets fonctionner une fois la vue créée.

L’emplacement de réplication se bloque

Symptôme — le pipeline se bloque et le journal WAL grossit sur le Postgres source.
Cause — un emplacement bloqué conserve le WAL ; une resynchronisation crée un nouvel emplacement.
Correction — sur votre propre Postgres managé, avec un seul emplacement et une marge importante, resynchronisez simplement le pipeline depuis la console. La suppression d’un pipeline supprime son emplacement sur la source. Tout pool managé de repli fourni par le formateur relève de sa responsabilité ; consultez infra/README.md.

Variables d’environnement

Une variable exportée dans l’interpréteur remplace .env.workshop

Symptôme — vous définissez une valeur dans .env.workshop, mais le conteneur en utilise une autre, souvent une ancienne valeur de OPENAI_API_KEY, une variable LANGFUSE_* ou CLICKHOUSE_PASSWORD.
Cause — docker compose remplace d’abord ${VAR} par la valeur de l’interpréteur, et une variable exportée dans celui-ci l’EMPORTE sur le fichier.
Correction — dans l’interpréteur depuis lequel vous exécutez Compose, lancez unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD, puis redémarrez la pile. La vérification préalable vous avertit lorsqu’elle détecte ce cas.

Clés en double dans .env.workshop

Symptôme — une valeur définie dans le fichier est ignorée.
Cause — la même clé apparaît deux fois ; la dernière occurrence l’emporte, conformément au comportement de docker compose, et la vérification préalable lit le fichier de la même manière.
Correction — supprimez le premier doublon afin de ne conserver que la valeur voulue.

Chat (module 08)

POST /api/chat renvoie une erreur 503 avec une indication de configuration

Symptôme — le panneau de chat affiche une indication de configuration et /api/chat renvoie une erreur 503 ; le reste de l’application fonctionne.
Cause — aucune valeur OPENAI_API_KEY n’est définie sur le back-end.
Correction — ajoutez OPENAI_API_KEY à .env.workshop, puis exécutez docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend. Le chat est la seule fonction qui en a besoin.

Impossible de créer une première clé OpenAI

Symptôme — OpenAI refuse de délivrer une clé API sur un nouveau compte.
Cause — les nouveaux comptes nécessitent une vérification téléphonique ponctuelle et ne disposent d’aucun crédit gratuit.
Correction — terminez la vérification téléphonique, puis ouvrez Settings -> Billing : ajoutez un moyen de paiement et achetez le minimum de 5 $ de crédit prépayé. Désactivez auto-recharge, activé par défaut pendant la configuration, afin de ne jamais être facturé au-delà des 5 $ ajoutés.

MCP et OAuth (modules 00 et 06)

Erreur 401 sur le point de terminaison MCP

Symptôme — un accès à https://mcp.clickhouse.cloud/mcp (ou /clickstack) renvoie une erreur 401.
Cause — ce résultat est attendu avant la fin du flux OAuth dans le navigateur ; le point de terminaison est authentifié.
Correction — ajoutez le serveur à votre agent, puis lancez le flux OAuth et autorisez l’accès dans le navigateur avec la commande de votre outil :
- Claude Code — exécutez /mcp, sélectionnez le serveur et autorisez-le (ou exécutez claude mcp login <name>).
- Codex CLI — codex mcp login <name>.
- Cursor — ouvrez le volet des paramètres MCP et cliquez sur la commande d’autorisation ou de connexion du serveur.
Vérifiez également que l’option Connect with MCP est activée pour votre service.

Un ordinateur professionnel bloque MCP ou OAuth

Symptôme — votre agent ne peut pas ajouter un serveur MCP ou la redirection OAuth est bloquée.
Cause — une politique de gestion de l’ordinateur interdit l’ajout de serveurs MCP ou les flux OAuth sortants.
Correction — une machine personnelle est la solution de repli la plus rapide.

Windsurf ne parvient pas à se connecter en HTTP natif

Symptôme — Windsurf ne parvient pas à se connecter au point de terminaison MCP ou son OAuth fonctionne de manière instable.
Cause — Windsurf se connecte par mcp-remote plutôt que par HTTP diffusé natif.
Correction — utilisez la forme de commande mcp-remote : { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } (remplacez /mcp par /clickstack lors de la connexion du MCP ClickStack au module 06).