トラブルシューティング

このワークショップの構築とテスト中に発生したすべての失敗について、症状、原因、修正方法をどこで表面化するかで分類したリファレンスです。

以下の項目はすべて、このワークショップの構築とテスト中に実際に起きた失敗です。自分の症状を見つけ、なぜそうなるのかを読み、修正を適用してください。ここに該当するものがない場合は、問題をコーディングエージェントに渡してください。自習ガイドに、エージェントを講師に変える、そのまま貼り付けられるプロンプトがあります。

Windows と WSL 2

`wsl --install` が使えない、またはヘルプしか表示されない

症状 - 管理者権限の PowerShell が wsl --install を認識しない、または Ubuntu をインストールせずにヘルプを表示する。
なぜ - Windows がワークショップの最低要件を下回っている、保留中の更新が適用されていない、または会社のポリシーが WSL を無効にしている。
修正 - Windows Update を実行し、Windows 11 または Windows 10 バージョン 2004 （ビルド 19041）以降であることを確認してください。再起動してから、 Microsoft の手動 WSL インストール手順に従います。管理されたマシンでは、必要な Windows の機能を管理者が許可する必要があります。

PowerShell でコマンドが「認識されません」と言われる

症状 - PowerShell が ./preflight.sh、export、source、またはワークショップの他の Bash コマンドを受け付けない。
なぜ - Windows のセットアップでは、明示的にラベル付けされた WSL のブートストラップにのみ PowerShell を使います。ワークショップのコマンドは WSL 2 上の Ubuntu 内で実行します。
修正 - スタートメニューから Ubuntu を開き、アプリディレクトリに戻ってそこで preflight を実行します。
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

リポジトリが `/mnt/c` 以下にある

症状 - Docker のバインドマウントが遅い、スクリプトでパーミッションや改行コードの失敗が起きる、またはリポジトリのパスが /mnt/c/Users/... で始まる。
なぜ - リポジトリが WSL の Linux ファイルシステムではなく、Windows のファイルシステム上にクローンされている。

修正 - コミットしていない作業が必要な場合にのみ、古いコピーを残してください。そうでなければ Ubuntu を開き、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 が WSL 1 で動いている

症状 - wsl --list --verbose が Ubuntu を VERSION 1 として表示する、または Docker Desktop がそのディストロと統合できない。
なぜ - そのディストロが WSL 2 より前のものか、WSL 1 をデフォルトとしてインストールされた。
修正 - PowerShell を管理者として 開いて変換し、Ubuntu を開き直します。
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

Ubuntu 内で `docker` が使えない

症状 - Docker Desktop は動いているのに、Ubuntu が docker: command not found と言う、またはデーモンに到達できない。
なぜ - Docker Desktop の WSL エンジンまたは Ubuntu との統合が無効になっている。
修正 - Docker Desktop -> Settings -> General -> Use the WSL 2 based engine と Resources -> WSL Integration -> Ubuntu を有効にし、変更を適用してから、PowerShell で wsl --shutdown を実行して Ubuntu を開き直します。その後は docker version が Client と Server の両セクションを表示するはずです。

WSL または Docker のメモリが 6 GB 未満

症状 - preflight がメモリ不足を報告する、または docker info --format 'Docker memory: {{.MemTotal}} bytes' が 6442450944 バイト未満を出力する。
なぜ - Docker Desktop の WSL 2 バックエンドは、WSL 仮想マシンのメモリ上限を使います。
修正 - Docker Desktop を終了し、PowerShell を開いて、WSL の上限を 8 GB に設定します。
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Docker Desktop を起動し、Ubuntu を開き直します。docker info のコマンドと preflight をもう一度実行してください。

スクリプトが `/usr/bin/env: 'bash\r': No such file or directory` を報告する

症状 - .sh ファイルがすぐに失敗し、エラーに bash\r または ^M が含まれる。
なぜ - Windows の CRLF 改行が、リポジトリが要求する LF 改行を置き換えてしまった。
修正 - Ubuntu で Git の WSL 向けポリシーを設定し、クリーンなチェックアウトを復元します。
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
何かを破棄したりコミットしたりする前に、git status を確認してください。そのチェックアウトに必要な作業がない場合は、~/ClickHouse_Demos にクリーンにクローンし直すのが最も安全な復旧策です。

OAuth が Windows のブラウザを開かない

症状 - MCP のログインが URL を表示するが、ブラウザのウィンドウが開かない。
なぜ - コーディングエージェントが WSL 内で動いており、ブラウザへの転送が利用できないか、会社のポリシーでブロックされている。
修正 - Ubuntu からログイン URL を完全にコピーし、通常の Windows のブラウザに貼り付けます。そこで認可を完了してから、Ubuntu のターミナルに戻ってください。

Docker

コンテナが「Created」のままで起動しない

症状 - docker info は正常に応答するのに、docker compose ... up がコンテナを Created のままにし、いつまでも healthy にならない。
なぜ - Docker エンジンが詰まっています。デーモンは応答するものの、実際にコンテナを起動できない状態です。ライブの立ち上げ中に OrbStack で確認されました。
修正 - Docker エンジン（Docker Desktop、OrbStack、または Colima）を再起動し、Running を報告するまで待ってから、スタックを再度起動してください。クローンしたリポジトリ内のどこからでも cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh を実行してください。使い捨てのコンテナをテストとして実行するので、スタックを起動する前にこれを検出できます。

up で「port is already allocated」になる

症状 - docker compose ... up が Bind for 0.0.0.0:8080 failed: port is already allocated（または :8000）で失敗する。
なぜ - 別のプロセス、または古いワークショップのコンテナが、そのホストポートをすでに掴んでいる。
修正 - クローンしたリポジトリ内のどこからでも cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh を実行してください。何がポートを掴んでいるかを示し、ベースポート + 20000 の規約に従って設定すべき上書き値を正確に出力します。たとえば set FRONTEND_HOST_PORT=28080 in .env.workshop のように。上書き用の変数は FRONTEND_HOST_PORT、BACKEND_HOST_PORT、そしてオブザーバビリティのオーバーレイ用の OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT です。提案された値を設定し、preflight を再実行してから、スタックを起動してください。動くのはホスト側のポートだけで、コンテナ内のポートは変わらないので、これは安全です。

「platform does not match」の警告

症状 - pull や up のときに Docker がプラットフォーム不一致の警告（たとえば linux/amd64 対 linux/arm64）を出す。
なぜ - イメージが自分のマシンとは別の CPU アーキテクチャ向けにビルドされています。 Apple Silicon ではよくあることです。
修正 - 無害です。これは失敗ではなく警告で、イメージはエミュレーションで動きます。そのまま進めてください。

ClickHouse Cloud

アイドル後の最初のリクエストが遅い、または一度だけ 500 になる

症状 - サービスがアイドルだった後の最初のクエリやダッシュボードの読み込みが遅い、またはリクエストが一度 500 になってから動くようになる。
なぜ - Cloud サービスはアイドルでゼロまでスケールし、復帰に約30秒かかります。最初のリクエストがその復帰コストを負担します。バックエンドはすでに最初の接続に長めのタイムアウトを許容し、一度リトライします。
修正 - 単に再試行するか、約30秒待ってください。これは障害ではありません。 07 テスト、故障、修復でも重要になります。復帰中のサービスは、fault 03 のタイムアウトをより発火しやすくします。

サービスのパスワードを紛失した

症状 - default ユーザーのパスワードを保存しておらず、見つけられない。
なぜ - サービスのパスワードは、作成フローを離れた後には再表示されません。
修正 - そのサービスを開き、Settings に移動して default ユーザーのパスワードをリセットし、.env.workshop の CLICKHOUSE_PASSWORD を更新してください。ホスト名はいつでも Connect のモーダルから取得できます。

マネージド Postgres のパスワードを紛失した

症状 - clickhousectl cloud postgres create が一度だけ表示した postgres 管理者パスワードを保存していない。
なぜ - 一度だけ表示され、ベータ版の postgres get / list API はインスタンスが正常でも空や FORBIDDEN を返すことがあります。
修正 - clickhousectl cloud postgres reset-password <service-id> を実行し、新しいパスワードを .env.workshop（PGPASSWORD）と ClickPipe の接続で使ってください。

ClickHouse Cloud に到達できない

症状 - preflight が接続性チェックで FAIL する、またはバックエンドが接続できない。 the command below が失敗する。

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"

なぜ - wifi、VPN、ファイアウォール、間違ったホスト（CLICKHOUSE_HOST にスキームやポートを貼ってしまった）、TLS やポートの不一致、または Cloud の IP アクセスリストが自分の IP をブロックしている。
修正 - CLICKHOUSE_HOST がホスト名のみ（https:// なし、ポートなし）であること、 CLICKHOUSE_PORT=8443、CLICKHOUSE_SECURE=true であることを確認し、VPN とファイアウォールを確認し、サービスの IP アクセスリストが自分のアドレスを許可していることを確認してください。 preflight は具体的な失敗（DNS、拒否、タイムアウト、TLS ハンドシェイク）を示します。

クライアントが `Unknown settings: ... skipping` を出力する

症状 - クエリは成功するが、実行するたびに未知の設定に関する警告が出る。
なぜ - ローカルにインストールされたクライアントが Cloud サーバーより新しく、そのサーバーリリースが認識しない設定を送っています。
修正 - モジュール 00 のステップ 6 にある、バージョンを揃えるコマンドをもう一度実行してください。clickhousectl 経由で Cloud サーバーのバージョンを読み取り、対応するメジャー／マイナーのクライアントリリースを選びます。--no-warnings でクライアントの警告をすべて隠すことはしないでください。

CDC（モジュール 03）

ClickPipe の作成が `table realtime_trips exists and is not empty` と言う

症状 - ClickPipe のリソースは存在しないのに、default.realtime_trips にすでに行があるため再作成が失敗する。
なぜ - ClickPipe を削除するとソース側のレプリケーションスロットは消えますが、宛先のテーブルが残ることがあります。新しいパイプは、その空でないテーブルを上書きしません。

修正 - 古い生の行をタイムスタンプ付きのバックアップ名で保存してから、パイプを作り直します。サービス ID のプレースホルダーは一度置き換えてください。これらのコマンドは、既存の materialized view もあれば保存します。

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}
"

モジュール 03 のステップ 3 をやり直し、新しい default.realtime_trips テーブルができるのを待ってから、ステップ 4 で正規の materialized view を作成してください。タイムスタンプ付きのバックアップは、そのデータがもう不要だと確認できてから削除してください。

ClickPipe が「Provisioning」のまま止まる

症状 - 作成した後、パイプがしばらく Provisioning を表示する。
なぜ - スナップショットとインフラの起動には通常数分かかりますが、この小さなテーブルでも 10分以上かかることがあります。
修正 - コンソール、または clickhousectl cloud clickpipe list <clickhouse-service-id> と clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id> の両方で進捗を確認してください。最初の数分間は、状態や updatedAt の値が進んでいる間は待ち続けます。 10分経っても更新がなく Provisioning のままの場合は、pg-trip-writer のログがまだ insert していることを確認し、ホスト、認証情報、パブリケーション、テーブルマッピングを再確認して、パイプが報告しているエラーを調べてください。最初のパイプがまだプロビジョニング中の間に、2つ目のパイプや materialized view を作成しないでください。ソース側のチェックが通り、Cloud が対応可能なエラーを報告していない場合は、get の出力を保存して講師または ClickHouse Cloud のサポートにエスカレーションしてください。

ClickHouse に行が届かない

症状 - パイプは Running なのに宛先の行数が増えず、Ops ダッシュボードも動かない。
なぜ - デフォルトの同期間隔が約60秒なので遅延が想定されます。あるいは生成器が insert していない、またはパイプが読むパブリケーションが存在しない。
修正 - 少なくとも60秒待ってください。pg-trip-writer のログに inserted N trips と、created publication pub_taxi（自分のインスタンス）または publication ... already exists（講師が用意したマネージドのフォールバック）のどちらかが出ていることを確認します。パイプの状態が Running であることを確認してください。パブリケーションがない場合、パイプには読むものがありません — 生成器は、自分が管理者であるインスタンスに対して初回実行時にそれを作成します。

materialized view に行がない

症状 - realtime_trips は埋まるのに、（CDC の materialized view が供給する）taxi_trips が空のまま。
なぜ - ClickPipe のターゲットが存在する前に materialized view が作成された、または CLI のターゲットである default.realtime_trips を読んでいない。
修正 - ターゲットのテーブルを待ってから、モジュール 03 のステップ 4 の materialized view のコマンド全体をコピーしてください。まずソースを検証します。
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
materialized view は、自身が存在するようになった後に insert された行を処理します。作成後は乗車データのライターを動かし続けてください。

レプリケーションスロットが停滞する

症状 - パイプが停滞し、ソースの Postgres で WAL が増えていく。
なぜ - 停滞したスロットは WAL を保持します。resync すると新しいスロットが作られます。
修正 - 自分のマネージド Postgres（スロット1つ、十分な余裕）なら、コンソールからパイプを resync するだけでよいです。パイプを削除すると、ソース側のスロットも消えます。講師側のマネージドなフォールバックのプールは講師側の関心事です — infra/README.md を参照してください。

環境変数

シェルの export が .env.workshop を上書きする

症状 - .env.workshop に値を設定したのに、コンテナが別の値を使う（多くは古い OPENAI_API_KEY、LANGFUSE_* のいずれか、または CLICKHOUSE_PASSWORD）。
なぜ - docker compose は ${VAR} をまずシェルから補完し、export されたシェル変数がファイルより優先されます。
修正 - compose を実行するシェルで unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD を実行してから、スタックを再度起動してください。preflight はこれを検出すると警告します。

.env.workshop にキーが重複している

症状 - ファイルに設定した値が無視される。
なぜ - 同じキーが2回現れており、docker compose の挙動に合わせて最後の出現が優先されます（preflight も同じように読みます）。
修正 - 先に現れる重複を削除し、意図した値だけが残るようにしてください。

チャット（モジュール 08）

POST /api/chat がセットアップのヒント付きで 503 を返す

症状 - チャットパネルがセットアップのヒントを表示し、/api/chat が 503 を返す。アプリの他の部分は問題ない。
なぜ - バックエンドに OPENAI_API_KEY が設定されていない。
修正 - .env.workshop に OPENAI_API_KEY を追加してから、 docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend を実行してください。これを必要とする機能はチャットだけです。

最初の OpenAI キーを作成できない

症状 - 新しいアカウントで OpenAI が API キーを発行しない。
なぜ - 新しいアカウントは一度だけの電話番号認証が必要で、無料クレジットはありません。
修正 - 電話番号認証を完了してから、Settings -> Billing で支払い方法を追加し、最低額の $5 のプリペイドクレジットを購入します。auto-recharge をオフ にしてください（セットアップ中はデフォルトでオンです）。そうすれば、追加した $5 を超えて課金されることはありません。

MCP と OAuth（モジュール 00 と 06）

MCP エンドポイントで 401 になる

症状 - https://mcp.clickhouse.cloud/mcp（または /clickstack）にアクセスすると 401 が返る。
なぜ - ブラウザでの OAuth フローを完了する前は想定どおりです。このエンドポイントは認証が必要です。
修正 - サーバーをエージェントに追加してから、OAuth フローを実行し、ブラウザで認可します。使うコマンドはツールごとに次のとおりです。
- Claude Code - /mcp を実行し、サーバーを選んで認可します（または claude mcp login <name>）。
- Codex CLI - codex mcp login <name>。
- Cursor - MCP 設定のペインを開き、そのサーバーの認可／ログインのコントロールをクリックします。
自分のサービスで Connect with MCP のトグルがオンになっていることも確認してください。

会社のノート PC が MCP または OAuth をブロックする

症状 - エージェントが MCP サーバーを追加できない、または OAuth のリダイレクトがブロックされる。
なぜ - 管理されたノート PC のポリシーが、MCP サーバーの追加や外向きの OAuth をブロックしています。
修正 - 個人のマシンを使うのが最も速いフォールバックです。

Windsurf がネイティブの HTTP で接続できない

症状 - Windsurf が MCP エンドポイントに接続できない、またはその OAuth が不安定。
なぜ - Windsurf はネイティブの streamable HTTP ではなく mcp-remote 経由で接続します。
修正 - mcp-remote のコマンド形式を使ってください。 { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } （モジュール 06 で ClickStack MCP を設定するときは /mcp を /clickstack に置き換えます）。