トラブルシューティング

このラボを進めるなかで受講者が遭遇する失敗について、症状・原因・対処をまとめたリファレンスです。症状が現れる箇所ごとに整理されています。

以下の項目はすべて実際の失敗です。ラボ自身のパート README に記載された11件に加え、このワークショップの構築とテスト中に見つかった5件です。自分の症状を探し、原因を読み、対処を適用してください。ここに一致するものがない場合は、講師トラックの ## Common failures セクションが各モジュールのファシリテーター側をより詳しく扱っています。その次の相談先は担当のソリューションアーキテクトです。

ツールチェーンとセットアップ

`dbt` が `mashumaro` のインポートエラーで失敗する、またはインストールできない

症状 - dbt-snowflake または dbt-clickhouse のインストールが失敗する、あるいは dbt が Python のバージョンとは一見関係のなさそうな mashumaro に言及するインポートエラーを出す。
原因 - dbt-snowflake と dbt-clickhouse はどちらも Python 3.11、3.12、または 3.13 を必要とします。Python 3.14 以上では両者が共有する mashumaro 依存関係が壊れ、その失敗は通常、間違いを犯したあとの無関係なモジュールで表面化します。
対処 - システムの Python と並べて 3.13 をインストールし（例: brew install python@3.13）、そのインタープリターを明示して仮想環境を作り直します: python3.13 -m venv .venv。

Snowflake のソース環境

`terraform init` がプロバイダーのエラーで失敗する

症状 - workshop_public/snowflake_migration_lab/01-setup-snowflake/ での terraform init がプロバイダーの解決中に失敗する。
原因 - Terraform のバイナリが古い、または Terraform レジストリへのネットワークアクセスがない。
対処 - Terraform >= 1.6 を使い、レジストリへのインターネットアクセスを確認します。

`snowsql` の接続が拒否される

症状 - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} が接続を拒否する。
原因 - SNOWFLAKE_ORG または SNOWFLAKE_ACCOUNT が間違っている。
対処 - 作成したアカウントと両方の値を照合し直し、同じ snowsql コマンドを再試行します。

`dbt run` が `relation not found` で失敗する

症状 - パート1の dbt プロジェクトでの dbt run が、存在しないリレーションを報告する。
原因 - データベースの構造が作成されていない。
対処 - 先に ./setup.sh --skip-seed を実行し、profiles.yml が NYC_TAXI_DB を指していることを確認します。

Superset が `connection refused` を表示する

症状 - docker-compose up の直後、パート1の Superset の UI が接続を拒否する。
原因 - Superset の初期化には約60秒かかります。
対処 - 60秒待って再試行します。それでも失敗する場合は docker logs nyc_taxi_superset を確認します。

データのシード投入が想定より長くかかる

症状 - workshop_public/snowflake_migration_lab/01-setup-snowflake/ のシード手順が止まっているように見える。
原因 - この規模では Snowflake の通常の挙動であり、ハングではありません。5,000万行を生成する TABLE(GENERATOR) の挿入に約10〜12分かかり、続いて5,000万行すべての VARIANT TRIP_METADATA カラムを埋める UPDATE に、SMALL ウェアハウスでさらに15〜20分かかります。
対処 - そのまま実行させてください。どちらの手順も対話的ではなく、再試行するものはありません。

ClickHouse Cloud のプロビジョニングとデータの移行

Terraform の認証が 401 Unauthorized で失敗する

症状 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ での Terraform の apply が 401 Unauthorized で失敗する。
原因 - CLICKHOUSE_TOKEN_KEY または CLICKHOUSE_TOKEN_SECRET が間違っている、あるいはキーに必要なスコープがない。
対処 - ClickHouse Cloud の UI の Settings -> API keys からキーペアを再生成し、 Admin スコープが付いていることを確認します。

マイグレーションスクリプトが実行中に失敗する

症状 - scripts/02_migrate_trips.py が5,000万行のコピーの途中で終了する。
原因 - 長時間の転送中に発生した一時的なネットワークまたはウェアハウスの不調。
対処 - --resume を付けて再実行します。スクリプトは ClickHouse にすでに存在する max(pickup_at) をウォーターマークとし、すでに読み込んだ行をスキップします:
```
python scripts/02_migrate_trips.py --resume
```

マイグレーションスクリプトの接続エラー

症状 - マイグレーションスクリプトが Snowflake または ClickHouse に到達できない。
原因 - 現在のシェルで Snowflake または ClickHouse の環境変数が1つ以上未設定になっている。
対処 - それらを確認し、再試行の前に state ファイルを source し直します:
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
まず source .env && source .clickhouse_state を実行し、それから再試行します。

`dbt run` が `Connection refused` または `Unknown host` で失敗する

症状 - ClickHouse プロジェクトに対する dbt run が、ホストの解決または接続に失敗する。
原因 - 現在のシェルで CLICKHOUSE_HOST が設定されていない。
対処 - モジュールのディレクトリから source .clickhouse_state を実行し、dbt run を再試行します。

`dbt` が `Could not find profile named 'nyc_taxi_ch'` で失敗する

症状 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch での dbt debug または dbt run が、プロファイルが見つからないエラーで即座に失敗する。
原因 - ClickHouse の dbt プロファイルが ~/.dbt/profiles.yml に追加されていない。
対処 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example を開き、その nyc_taxi_ch: ブロックを2つ目のトップレベルプロファイルとして既存の ~/.dbt/profiles.yml にマージします。ファイルを上書きしないでください。 上書きするとモジュール01の nyc_taxi: プロファイルが消え、その手順4のリフレッシュループが壊れます。このマージ手順を詳しく扱っている 03 プロビジョニングと移行を参照してください。

ClickHouse 上の dbt

dbt の実行後に `analytics.agg_hourly_zone_trips` が空である

症状 - モジュール04の dbt run のあと、analytics.agg_hourly_zone_trips の行数がゼロで、それを使うダッシュボードのチャートにデータが表示されない。
原因 - これは想定どおりで、失敗ではありません。このモデルの増分フィルターは WHERE pickup_at >= now() - INTERVAL 2 HOUR であり、稼働中の trip プロデューサーが書き込んだ行にしか一致しません。マイグレーションスクリプトが移した行はすべて過去のものなので、その2時間のウィンドウには1行も入りません。
対処 - 直すものはありません。ここではゼロが正しい値です。 05 ベンチマークとカットオーバーのカットオーバー手順のあと、プロデューサーが直接 ClickHouse に書き込むようになると、このテーブルは埋まります。

ダッシュボードとベンチマーク

Superset が 403 Forbidden を表示する

症状 - モジュールの途中で Superset の UI が 403 Forbidden を返す。
原因 - セッションの cookie が期限切れになった。
対処 - ログアウトし、http://localhost:8088 で再度ログインしてから、 bash superset/add_clickhouse_connection.sh を再実行します。

ベンチマークで Q7 が `N/A` になる

症状 - run_benchmark.sh の出力 CSV で、クエリ7の高速化の値が N/A になっている。
原因 - ベンチマークスクリプトが ClickHouse に接続できなかった。
対処 - CLICKHOUSE_HOST が設定されていること（source .clickhouse_state）と、サービスが稼働していることを確認し、ベンチマークを再実行します。

インポートした Superset のダッシュボードが ClickHouse に接続できない

症状 - Superset にインポートしたダッシュボードは読み込まれるが、そのチャートが ClickHouse に到達できない。
原因 - コミット済みのエクスポート ZIP は、ホストが your-instance.clickhouse.cloud に置き換えられています。add_clickhouse_connection.sh はインポート前に .env から実際の URI をパッチしますが、Superset の UI からの手動インポートはそれをしません。
対処 - 手動インポートではなく bash superset/add_clickhouse_connection.sh を使うか、あとから接続を編集して実際の CLICKHOUSE_HOST と認証情報を使うようにします。

カットオーバーとパリティ

パリティチェックが失敗する、またはカットオーバーで行が失われたように見える

症状 - モジュール05の行数パリティチェックが失敗する、あるいはカットオーバーでデータを落としたように見える。
原因 - --resume の追いつきパスが飛ばされました。Snowflake のプロデューサーはモジュール 01〜05を通して継続的に書き込むため、モジュール03のマイグレーションはデータの先頭部分しか捉えていません。末尾は、追いつきを行うまで Snowflake にしか存在しません。Snowflake のプロデューサーを早く止めてしまうと（たとえばモジュール01の直後に）、追いつくべき末尾が残らないため、このモジュールのカットオーバーの実演が黙って壊れます。
対処 - パリティを確認する前に追いつきパスを実行します。ギャップの行だけを移すので、元の40〜50分ではなく数秒から数分で終わります:
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```